Notes on Using Claude Code

Claude Code works best when I treat it as an agentic development environment, not as a smarter autocomplete. It can read files, run commands, edit code, and keep working through a problem while I supervise. That makes it powerful, but it also means the workflow needs more discipline than a normal chatbot prompt.

The most useful idea from Anthropic’s best practices is that Claude needs feedback loops. If I only ask it to “make the page better”, I become the only judge of success. If I give it tests, screenshots, command output, constraints, and a definition of done, Claude can check itself and repair failures before handing work back.

1. Give Claude a Way to Verify the Work

Verification is the highest-leverage habit. Claude performs much better when it can run a command, compare output, or inspect a screenshot instead of guessing whether the result is correct.

For this blog, a normal content or style change should end with:

npm run clean && npm run build

For JavaScript behavior, I also want:

node --check themes/kaomoji-pixel/source/js/home.js

For UI changes, the request should include the viewport and the behavior to inspect:

Change the mobile article layout.
Verify it at 400px wide.
The page shell must fit the viewport.
Long code blocks should scroll inside the block, not stretch the window.
Run the build after fixing it.

The important part is not the exact command. The important part is giving Claude an objective finish line. “Looks good” is weak. “The build passes and the mobile code block no longer overflows” is much stronger.

2. Explore First, Then Plan, Then Code

Claude Code can edit quickly, but fast editing is not the same as correct editing. For unclear work, I prefer a three-step rhythm:

1. Explore the relevant files without editing.
2. Explain the existing behavior and propose a plan.
3. Implement only after the plan is clear.

A good planning prompt looks like this:

Inspect the article layout and CSS first.
Do not edit files yet.
Identify which templates, styles, and scripts are involved.
Then propose a short implementation plan and call out risks.

This is useful when the change touches routing, page shell behavior, music playback, responsive layout, or deployment. It prevents Claude from solving the wrong problem with a confident patch.

For small changes, planning can be skipped. If I can describe the diff in one sentence, I usually let Claude make the change directly. For example:

Remove code block line numbers from Hexo output and keep the terminal-style copy button.
Run the build and commit the change.

The point is to choose the amount of ceremony based on risk.

3. Provide Specific Context

Claude can infer a lot, but precise context still saves time. I try to include:

• the file or directory that probably matters
• the current symptom
• the desired behavior
• constraints that must not change
• commands that prove the work is done

Bad prompt:

Fix the blog layout.

Better prompt:

Fix the mobile layout for /zh/posts/codex-notes/.
The code block currently overflows the window at 400px width.
Keep the desktop layout unchanged.
Do not re-add article navigation.
Run npm run clean && npm run build.

Claude also handles richer context well. I can paste screenshots, logs, URLs, or specific error output. For codebase references, it is better to name real files than to describe them vaguely.

4. Keep CLAUDE.md Short and Useful

CLAUDE.md is project memory. It should contain rules Claude cannot reliably infer from the codebase:

# Workflow

- Run `npm run clean && npm run build` after content or theme changes.
- Run `node --check themes/kaomoji-pixel/source/js/home.js` after JavaScript changes.
- Commit after each completed small feature loop.
- Do not restart the audio player during local navigation.
- Keep the page shell fixed; long content scrolls inside `.window-content`.

I do not want this file to become a manual. If a line does not prevent a real mistake, it should probably be removed. Long instruction files are easy to ignore because the important rule gets buried under obvious advice.

For this project, the Codex equivalent is AGENTS.md plus .spec/README.md. The principle is the same: durable rules belong in versioned project guidance, not in every prompt.

5. Configure Permissions Around Trust

Claude Code often asks for permission before file writes, shell commands, MCP tools, or other side effects. That is useful when the project is unfamiliar, but it can slow down trusted repetitive work.

My practical rule:

• use tighter permissions for unfamiliar repositories
• allow known-safe commands for personal projects
• keep destructive commands manual
• let verification commands run freely when they are part of the workflow

For example, it is reasonable to allow:

npm run build
npm test
git status
rg

But I still want caution around deployment, credential changes, production database commands, or anything that rewrites history.

6. Use CLI Tools and MCP for External Context

Claude Code is strongest when it can use the same tools I use. If the task involves GitHub, cloud resources, logs, or docs, the CLI is often more efficient than asking Claude to reason from memory.

Useful examples:

gh issue view 123
gh pr diff 456
aws logs tail /service/api --since 30m

MCP is useful when the external context is repeated: issue trackers, docs, dashboards, databases, Figma files, or observability tools. I would not connect everything by default. I add MCP when it removes a real manual loop.

7. Use Hooks for Rules That Must Always Run

Project instructions are advisory. Hooks are deterministic.

If a task must happen every time, it belongs in a hook or a script. Examples:

• run a formatter after file edits
• block writes to generated files
• run a focused linter after changing a package
• prevent commits with failing tests

I would start with instructions first, then turn stable repeated checks into hooks after the workflow proves itself.

8. Use Skills and Subagents Carefully

Skills are useful for reusable workflows that are too specific for general instructions. A skill should be narrow:

review a PR against this team's checklist
write release notes from commits
triage a production log bundle
apply this service's API conventions

Subagents are useful when research would consume too much context. For example:

Use a subagent to inspect how authentication handles token refresh.
Summarize reusable utilities and edge cases.
Do not modify files.

This keeps the main session focused on implementation. I would use subagents for investigation, review, or parallel research, not for tightly coupled edits that need constant coordination.

9. Manage Context Aggressively

Context is a resource. Long sessions collect file contents, command output, wrong turns, and old requirements. At some point, Claude starts carrying too much history.

My current habits:

• use one session for one coherent task
• run /clear between unrelated tasks
• use /compact when the task is still active but context is getting long
• use /rewind or checkpoints when an approach goes wrong
• resume named sessions when returning to the same workstream

If I have corrected Claude twice on the same issue, I usually stop and rewrite the prompt with the new information. A clean session with a precise prompt is often better than a long session full of corrections.

10. Scale Only After the Manual Workflow Works

Claude Code can run non-interactively and can be fanned out across many files, but automation should come last.

A simple non-interactive command can be useful:

claude -p "Explain what this project does"

For scripts, structured output matters:

claude -p "List API endpoints as JSON" --output-format json

For large migrations, I would test the prompt on two or three files first, fix the prompt, then run it across the full set. Parallel sessions and worktrees are powerful, but they also create coordination cost. The safe pattern is:

manual workflow -> stable prompt -> small batch -> broader automation

11. Common Failure Patterns

The mistakes I want to avoid are predictable:

• one endless session that mixes unrelated tasks
• vague prompts with no verification step
• overgrown CLAUDE.md files
• treating generated code as correct because it looks plausible
• letting Claude explore the whole codebase without a narrow question
• automating a workflow before I understand it manually

Most of these failures are process failures. Claude Code becomes much more reliable when the process gives it boundaries, context, and feedback.

My Current Rule

I want Claude Code to handle the mechanical loop:

inspect -> plan -> edit -> verify -> fix -> summarize

I still own the product direction. Claude can move fast through implementation details, but I need to decide what should exist, what tradeoffs are acceptable, and when the result is good enough to ship.

Source

This article summarizes and adapts ideas from Anthropic’s Claude Code best practices guide:

https://code.claude.com/docs/en/best-practices