Claude Code for Development: The Basics

Claude Code becomes useful when you stop treating it like a chat window and start treating it like a development tool inside the repo.

It can read files, inspect structure, run commands, edit code, and work with git context. That is the benefit. It is also the risk. A tool that can change files should be given the same boundaries you would give any developer working in your project.

The official Quickstart covers installation, login, starting a session, making a first code change, and using git. This note is the basic workflow I would use after setup.

Start from the project root

Open the terminal in the repository and start a session:

claude

The current quickstart lists native installers for macOS, Linux, WSL, and Windows, plus Homebrew and WinGet options. It also points out that Claude Code is available in other surfaces, including web, desktop, IDE integrations, Slack, and CI/CD.

For normal development, I still prefer the terminal at the repo root. That gives the tool access to the same project files, scripts, and git state I am using.

First prompt: understand the codebase

Do not start with a broad implementation request in a codebase you have not explored.

Start with a map:

Give me a high-level overview of this codebase.
Call out the main folders, data sources, routes, tests, and build commands.
Do not suggest changes yet.

Then narrow it:

Trace how writing posts are loaded, sorted, rendered, and added to RSS.
Include the files involved and the data flow.

The common workflows docs recommend this same broad-to-specific pattern for understanding new codebases. It works because the tool learns the local names before making recommendations.

Ask for plans before edits

For small content changes, direct editing is fine. For anything with multiple files, ask for a plan before touching disk.

Plan the smallest safe change for adding a new writing post type.
Include files to touch, expected behavior, and verification commands.
Do not edit files yet.

This gives you a checkpoint. You can catch a bad assumption while it is still text.

When the plan is right, make the implementation request narrow:

Implement the plan.
Stay within the files listed.
Do not run formatters that rewrite unrelated files.
Run tests and build after editing.

That scope matters. Claude Code can be fast, but fast work still needs a fence.

Debug with reproduction, not vibes

The weakest debugging prompt is:

Tests are broken. Fix them.

A better prompt gives evidence:

`pnpm test` fails in ProjectCard.test.ts.
Find the root cause before editing.
Explain the failing assertion, then propose the smallest fix.

If you have a stack trace, paste it. If the bug is intermittent, say so. If there is a command that reproduces it, give the command.

Claude Code is much more useful when it can run the same failure you are seeing.

Use tests as the contract

Claude Code can write tests quickly. That does not mean every generated test is useful.

Bad request:

Add tests.

Better request:

Add tests for the mobile nav menu.
Follow the existing component test style.
Cover initial closed state, open after click, and close after selecting a link.
Assert rendered behavior, not implementation details.

That tells the tool what behavior matters.

After changes, run the project checks. In this portfolio, the normal sequence is:

pnpm test
pnpm lint
pnpm build

If a command fails, fix the failure. Do not accept “it should work now” as evidence.

Review the diff before trusting it

The most important Claude Code habit is still reading the diff.

Ask for a summary:

Summarize the diff by behavior change.
Flag risky changes, public API changes, missing tests, and unrelated edits.

Then inspect the diff yourself.

This is especially important in a dirty working tree. If other work is already in progress, name the allowed files and tell the tool not to touch anything else.

Only edit files under src/content/writing.
Do not modify project data, components, tests, or config.

That one sentence can prevent a lot of cleanup.

Put repeated instructions in the project

If you repeat the same rules every session, move them into project instructions.

Claude Code supports CLAUDE.md for repository guidance and hierarchical settings across user, project, local, and managed scopes. The settings docs describe project scope as the place for shared settings such as permissions, hooks, MCP servers, and plugins.

Good project instructions include:

• How to run tests
• Commit message format
• Code style preferences
• Files that should not be edited
• Review expectations
• Deployment notes

Keep the file practical. A short rule that gets followed is better than a long manifesto that gets ignored.

Use skills for repeated workflows

Claude Code skills are reusable instructions that can be invoked with slash commands. The docs describe them as a good fit when you keep pasting the same checklist or multi-step procedure into chat.

Useful examples:

• Review this diff
• Add a writing post
• Debug failing tests
• Prepare a pull request summary
• Audit a page for accessibility issues

Skills are cleaner than stuffing every workflow into one instruction file because the skill body loads only when needed.

The basic loop

The workflow is simple:

1. Explore the codebase
2. Ask for a plan
3. Edit within scope
4. Run tests and build
5. Review the diff
6. Iterate on failures

That is normal engineering discipline. Claude Code just makes the loop faster when you keep the boundaries clear.