Claude Code

Best practices and workflows

Explore-plan-implement, verification, context, subagents, worktrees, headless execution, and review practices.

This combines official best practices and workflows into practical steps. For commands, see Command reference. For the agent loop and extension roles, see How it works; for copyable prompts, see Prompt library.

#Working process

Claude reads context, decides an action, calls a tool, observes the result, and repeats. Clear boundaries and verification improve reliability.

Phase	You supply	Claude does
Explore	Goal, directories, no-edit instruction	Read code, map dependencies, identify risks
Plan	Constraints, acceptance criteria, checks	Propose steps and tradeoffs
Implement	Allowed files	Make focused changes
Verify	Lint/types/tests/build/screenshots	Gather evidence and fix regressions
Review	Defect-focused review request	Find bugs, risks, missing tests

#Provide a verifiable path

Fix the login page's mobile layout.
Afterward run npm run lint, npm run typecheck, and npm run build.
Check at 390px and 1440px that buttons do not overlap.

When checks are unknown:

Find validation commands in package scripts, CI configuration, and README.
Choose the smallest relevant validation set before implementing.

#Explore before implementing

Explore this module read-only. Identify data flow, key files, tests, and risks.
Do not modify files. Finish with an implementation plan of at most six steps.

When ready to proceed:

Implement the plan. Validate each meaningful part and avoid unrelated files.

#Supply concrete context

Include user/scenario, editable directories, protected behavior, logs/screenshots, acceptance criteria, and compatibility/rollback needs.

Make the documentation search dialog usable on mobile.
Scope: src/components/DocsClientControls.tsx and src/app/globals.css.
At 320px there must be no overflow; Esc closes it; Tab stays inside;
light/dark text remains readable. Run lint, typecheck, and build.

#Write useful CLAUDE.md instructions

Store stable knowledge a new teammate needs:

CLAUDE.md

# Project conventions

- Use npm; do not introduce a pnpm lockfile.
- Documentation lives in content/docs.
- After UI changes, run npm run lint, npm run typecheck, and nice -n 10 npm run build.
- Port 3017 hosts the static preview; do not restart it. Builds refresh out.
- Do not store API keys in project .claude/settings.json.

Do not store one-off tasks, obsolete bugs, copied logs, or rely on prose for enforceable security restrictions.

#Permissions, hooks, and environment

Need	Approach
Pre-approved test commands	Narrow allow rules
Protect secrets	Permission rules plus appropriate hook/isolation checks
Lint after edits	PostToolUse
Network restrictions	Command rules, hooks, sandbox
Shared team settings	Project .claude/settings.json
Personal key	User environment/settings

See Permissions, Hooks, and Sandboxing.

#Subagents and parallel work

Delegate independent exploration/review without blocking the main critical path unnecessarily.

Have a subagent inspect mobile styling read-only while the main session updates docs.
Return file/line locations and recommendations; do not edit files.

Assign ownership to writers:

Worker A owns content/en/docs/claude-code/*.mdx.
Worker B owns src/app/globals.css.
Do not revert each other's work.

Use worktrees for isolation.

#Manage context

Symptom	Action
Window nearly full	Compact or start a new session
Repeated large logs	Filter key failures
Large repository	Locate with rg before reading
Drifting task	Restate acceptance criteria briefly
Need an earlier state	Rewind or Git

Stable model/effort favors reuse. Major instruction/tool/style changes alter prefixes. Compaction shortens context but also changes the conversation cache. See Caching and Command effects.

#Common workflows

#Learn a repository

Explore read-only. Report the stack, entry points, main data flow,
test/build commands, and high-risk areas. Do not edit files.

#Fix a bug

Reproduce the bug with an existing test or minimal example before changing code.
Fix it, run the relevant tests and global lint/type checks.

#Refactor

Refactor without changing behavior. Identify public interfaces and coverage first.
Make small changes and explain why behavior remains the same.

#Write documentation

Update docs from the implementation, tests, and official references.
Do not guess API behavior. Retain authoritative links.

#Prepare a PR

Describe the current diff: problem, changes, validation, risks, and rollback.

#Headless script

claude -p "Review this diff for bugs. Return JSON with severity, file, line, finding." \
  --output-format json

Bound input size instead of sending the entire repository and full logs.

#Anti-patterns

Pattern	Consequence	Better approach
Optimize the project	Unbounded scope	Goal, metrics, allowed scope
No checks	Superficial completion	Supply or discover checks
Overlapping writers	Conflicts/overwrites	Ownership/worktrees
Secrets in prompts	Context/log exposure	Environment/secret storage and restrictions
Unmanaged long context	Cost and lost focus	Inspect, compact, start fresh
Security only in CLAUDE.md	No enforcement	Permissions, hooks, isolation

#Official references

PreviousOutput styles NextPrompt templates and team adoption

Support

Need help?

For setup, billing, or model issues, email us. Check the status page for uptime.

Support Email[email protected]Service Statusstatus.passion8.cc

WeChat / QQ support is available at the bottom right.