# Claude Code Best practices and workflows

> Claude Code: Explore-plan-implement, verification, context, subagents, worktrees, headless execution, and review practices.

URL: https://docs.passion8.cc/en/docs/claude-code/best-practices-workflows
Language: en
Publisher: Passion8

This combines official best practices and workflows into practical steps. For commands, see [Command reference](https://docs.passion8.cc/en/docs/claude-code/commands). For the agent loop and extension roles, see [How it works](https://docs.passion8.cc/en/docs/claude-code/how-it-works); for copyable prompts, see [Prompt library](https://docs.passion8.cc/en/docs/claude-code/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

```text
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:

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

## Explore before implementing

```text
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:

```text
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.

```text
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:

```markdown title="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](https://docs.passion8.cc/en/docs/claude-code/permissions), [Hooks](https://docs.passion8.cc/en/docs/claude-code/hooks), and [Sandboxing](https://docs.passion8.cc/en/docs/claude-code/sandboxing).

## Subagents and parallel work

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

```text
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:

```text
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](https://docs.passion8.cc/en/docs/claude-code/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](https://docs.passion8.cc/en/docs/claude-code/prompt-caching) and [Command effects](https://docs.passion8.cc/en/docs/claude-code/command-cache).

## Common workflows

### Learn a repository

```text
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

```text
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

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

### Write documentation

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

### Prepare a PR

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

### Headless script

```bash
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

- [Best practices](https://code.claude.com/en/docs/en/best-practices.md)
- [Common workflows](https://code.claude.com/en/docs/en/common-workflows.md)
- [How it works](https://code.claude.com/en/docs/en/how-claude-code-works.md)
- [Memory](https://code.claude.com/en/docs/en/memory.md)
- [Worktrees](https://code.claude.com/en/docs/en/worktrees.md)