Research Notes

Claude Code Quickstart: Four Principles

3 min read

This is the main Claude Code quickstart. You do not need a feature tour first. You need four habits that make agents fast without letting them drift into confident nonsense.

1. Voice dictation

The main speedup is talking to the computer. Claude Code is useful because you can explain intent, constraints, tradeoffs, and corrections faster than you can type or manually edit.

Set up OS speech-to-text first: macOS Dictation, Windows voice typing, or a reliable Linux transcription path that pastes into your terminal or editor. Then put cleanup rules in your global CLAUDE.md, so spoken prompts are handled as spoken prompts:

  • Treat messages as speech-to-text unless told otherwise.
  • Remove filler, false starts, repeated words, and obvious transcription errors.
  • Preserve pasted code, logs, file paths, stack traces, quoted text, and commands verbatim.

My takeaway is that repository-level context files should probably be kept shorter and more specific and perhaps ideally hierarchical (e.g., “if you do x, check this other context file y.md, otherwise ignore it”).

2. Parallel work

Do not treat one chat as the only lane of work. Use Git worktrees when you want to try multiple approaches without contaminating the same checkout:

git worktree add ../project-a -b try/a
git worktree add ../project-b -b try/b

Use subagents for bounded parallel jobs: review the plan, inspect likely causes of a failure, compare approaches, write a focused smoke test, or check a UI with screenshots.

The point is comparison, not more code. Let the agent produce candidate answers, then compare diffs, failure modes, test coverage, and maintainability before merging one path.

3. Test-driven development

Start by defining what passing means. Before implementation, ask for the tests, checks, evals, screenshots, or acceptance criteria that will prove the task is done.

Make this explicit TDD:

  • For logic, write or name the unit tests first.
  • For workflows, define the integration or smoke test.
  • For UI, require a rendered browser check and screenshots.
  • For model behavior, create eval cases.
  • For data transforms, lock fixtures and expected output.

Agents write plausible garbage unless forced through real tests. “It runs” is not enough. The standard is: does it pass the actual quality measure that matters for this task?

4. Plan first

Use planning mode before coding, especially for new projects, migrations, architecture changes, unclear data contracts, or anything expensive to unwind.

Ask Claude Code to grill you before it writes code:

  • What is the smallest useful version?
  • What should change, and what should stay untouched?
  • What contracts, files, and commands matter?
  • What tests prove success?
  • What are the likely failure modes?
  • What is the rollback path?

A good plan makes implementation boring: scoped files, explicit tests, known risks, and a clear stopping point.

Meta-tip

One thing to understand about AI agents: you can ask them how to use the AI itself. For a hard task, ask Claude Code how to use Claude Code better on that task: what context to provide, which tests to write first, which subagents to use, and what failure modes to watch.