Reading Guide
To build a Claude Code workflow, you can first clearly define project rules, allowed actions, and result verification methods before considering Hooks, MCP, or multi-agent collaboration. This article compiles Cal Rueb's historical share from Q2 2025, and is not a feature list for the current version.
If you find yourself repeatedly explaining the same rules for a project, start with Section 3 on CLAUDE.md; if you need to control execution scope, see Section 4; if long conversations lead to information chaos, see Section 5. Sections 8 and 9 discuss Hooks and MCP respectively, which are suitable for selection based on specific problems after the basic workflow is running smoothly.
First test with a small, rollback task to check: whether rules are read, whether execution actions comply with permissions, and whether results are reproducible and pass acceptance. Original commands, reasoning levels, and permission behaviors may change with versions; before use, refer to the official documentation for your installed version; multi-agent setups also do not automatically guarantee faster or more accurate results.
Recommended further reading:
When to open: You want to know how Claude Code is used internally at Anthropic and what "counterintuitive" best practices exist. This wiki is a compilation of Cal Rueb (engineer on the Anthropic Claude Code team)'s share on the Newtype planet in Q2 2025.
Compared with Wang Kai's Claude Code Terminal Workflow Methodology (Full Version) differences: Wang Kai's piece is "an independent developer's product-perspective methodology + multi-Agent orchestration". This wiki is "an Anthropic internal engineer's perspective on tool usage + mental models". It is recommended to read both for comparison.
1. Design Philosophy of Claude Code
Cal emphasized from the start: Claude Code is not an IDE, nor a Copilot; it is an "Agent in the terminal".
| Tool | Mental Model | Trust Scale |
|---|---|---|
| Cursor / Copilot | "Completer" inside an IDE | You are driving |
| Devin / Manus | "Robot" that runs tasks automatically | It is driving |
| Claude Code | Your "engineer colleague" | Collaboration — you make product decisions, it handles implementation details |
Key implications:
- Claude Code works with you in collaboration, it does not replace you to write code. You give direction, it produces code, you review, and you commit
- It "lives" in the terminal, because the terminal is the environment engineers are most familiar with; do not treat it as a GUI
- It "comes with built-in git / bash / filesystem access" — that is why it is powerful and also dangerous
2. Agentic Search vs RAG
Cal's counterintuitive judgment: Claude Code does not use RAG; it uses Agentic Search. This is the fundamental difference between it and other AI editors.
2.1 Comparison of the two
| Dimension | RAG (Vector Retrieval) | Agentic Search(Claude Code) |
|---|---|---|
| Working method | Pre-embed, retrieve top-k at query time | Whenever needed, the Agent itself uses grep / glob / read / ls |
| Context | Fixed window, fetched by semantic similarity | Dynamically decides which file to look at, and down to which line |
| Accuracy | Depends on embedding quality, often fetches wrong content | LLM searches directly with tools, high precision |
| Latency | Fast retrieval | Slightly slower due to multiple rounds of tool calls |
| Suitable scenarios | Static document libraries | Living codebases |
2.2 Cal's explanation
"RAG scans a book's table of contents into vectors, then uses similarity to find pages. But code is not a book; code is a graph — files import each other, functions call each other. When an LLM holds grep / glob, it is like an engineer holding find / ag; that is the correct way to search code."
Practical implications:
- Do not add RAG MCP to Claude Code — its built-in search capability is stronger than RAG
- Let Claude Code explore the codebase on its own; do not pre-feed it "code summaries I organized"
- Large codebases (>100k lines) still work, because it only looks at a few relevant files each time
3. CLAUDE.md: Multi-level Configuration
Cal emphasized: CLAUDE.md is the most important configuration file for Claude Code. There are 3 levels, which take effect when merged.
3.1 The three levels
| Level | Path | Purpose |
|---|---|---|
| Global | ~/.claude/CLAUDE.md |
Your personal preferences (communication style, naming conventions) |
| Project | <project>/CLAUDE.md(committed to git) |
Team-shared project conventions (architecture, style, build commands) |
| Private | <project>/CLAUDE.local.md(not committed to git) |
Your personal preferences for this project |
Merge order: Global → Project → Private; later levels override earlier ones.
3.2 What content should go into CLAUDE.md
Cal recommends:
- Project structure(directory tree, where key modules are located)
- Build / test commands(
pnpm dev,pytest,make build) - Code style(2 spaces vs 4 spaces, string quotes, naming conventions)
- Architectural iron rules("API calls must go through src/api/", "Database schema changes must be migrated")
- Pitfalls to avoid("Do not touch legacy/auth.py", "Do not use mocks in tests; use docker to start postgres")
- Usage preferences for MCP tools
3.3 What should not go into CLAUDE.md
- Your passwords / API keys (use environment variables)
- Large code snippets (use imports or links)
- Content unrelated to work (use CLAUDE.local.md for personal preferences)
- Imperative statements like "You must X" — Cal emphasizes using "We prefer X because Y"; LLMs follow instructions with reasons better
4. Permission System: Three Granularities
Claude Code's power comes from the fact that "it can access your git and bash". Permissions are a key point Cal emphasized.
4.1 Three Permission levels
| Level | Description | Usage |
|---|---|---|
| Ask | Asks you for every tool call | New projects / dangerous tasks |
| AcceptEdits | Read / Write / Edit pass automatically, Bash still asks | Medium trust |
| BypassPermissions | Fully automatic | Sandbox environments / tasks you fully trust |
Switching:Shift+Tab switch instantly.
4.2 Cal's recommendations
- Never use "BypassPermissions" on production codebases. Even if you are in a hurry, at least use AcceptEdits + Bash review
- Dangerous command list:
rm -rf,git push --force,DROP TABLE,sudo, writing files to paths outside~the project - Hooks mechanism(next section) can automatically block dangerous commands
4.3 Permission Modes (not mentioned by Cal but present in official documentation)
- Plan Mode: Let Claude Code plan first before executing (does not enter Plan by default)
- Read-only Mode: Can only read, not modify (suitable for having Claude Code do code review)
5. Context Management:/clear and /compact
Cal calls these the two "most commonly used but most underrated" commands in Claude Code.
5.1 /clear
Function: Clears the entire conversation context and starts fresh.
When to use:
- Task switching (just finished feature A, about to work on feature B)
- The conversation gets long but has gone off track (Claude Code is repeatedly retrying the same error)
- You want to change your approach and start over
Cal's statistics: He himself averages10–20 /clear per day. One /clear per small task.
5.2 /compact
Function: Does not clear, but lets Claude Code summarize the current context, compressing the detailed conversation into a summary.
When to use:
- Context is approaching the token limit (default 200k, Sonnet 4.6 can reach 1M)
- The task is long and a "savepoint" is needed in the middle
- You want to preserve the train of thought but reduce consumption
Cal's recommendation:
- Run /compact once every 50% context
- But do not start a new task immediately after /compact — first confirm that the compacted summary contains key information
6. Think Hard: Three Levels of Reasoning
Claude Code has 3 built-in "thinking intensity" keywords(corresponding to different levels of extended thinking):
| Keyword | Intensity | Token consumption | When to use |
|---|---|---|---|
think |
Low | ~4k thinking tokens | Simple decisions (no need to use it for fixing typos) |
think hard |
Medium | ~10k | Debugging / refactoring |
think harder / ultrathink |
High | ~32k | Architecture design / complex bugs |
6.1 Cal's usage
- 95% of conversations do not use think; just let Claude Code do the work directly
- For 5% of complex tasks, add "think hard" or "ultrathink" at the end of the prompt
- Do not use ultrathink every time; it wastes tokens and slows down responses
6.2 Cal's counterintuitive advice
"If you find yourself repeatedly using ultrathink, it means your task granularity is too large.Split the task into smaller ones; think hard is enough for each small task. "
7. Sub-Agents: Parallelism + Boundaries
Claude Code supports Sub-Agents, which Cal emphasizes is the "most underrated feature".
7.1 What a Sub-Agent is
- Uses the Task tool to launch a new Claude Code instance with its own independent context
- The main Agent gives it a prompt, and it returns results after finishing
- Multiple Sub-Agents can run in parallel
7.2 Cal's recommended Sub-Agent usage
| Scenario | What the main Agent does | What the Sub-Agent does |
|---|---|---|
| Large codebase exploration | Integrates Sub-Agent outputs | Scans different directories in parallel |
| Multi-file refactoring | Coordinates and does the final commit | One Sub-Agent modifies each file |
| Research and comparison | Decides which option to choose | One Sub-Agent runs a spike for each option |
| Code Review | Integrating feedback | One Sub-Agent reviews each module |
7.3 Boundaries for Sub-Agents
- Do not let Sub-Agents do commit / push (the main Agent does this centrally to avoid conflicts)
- Do not let Sub-Agents start dev servers (processes will become orphaned, and the main Agent will not know)
- Do not tell Sub-Agents in the prompt to "find all X" — their context window limits make them miss things more severely than the main Agent
- When Sub-Agents write code, the main Agent must review it
7.4 Actual benefits of multi-Agent parallelism
Cal gave a statistic:With 4 Sub-Agents in parallel, total time is ~1.3x that of a single Agent, far less than 4x. The reason is that Sub-Agent startup + return overhead is large, but work inside a single task is fast.
Therefore:
- Running 4 Sub-Agents simultaneously on 4 independent modules is cost-effective
- Running 4 Sub-Agents on 4 interdependent small steps is a loss (using the main Agent serially is faster)
8. Hooks: Behavior Triggers
Claude Code supports Hooks(user / project level), which trigger custom scripts on specific events.
8.1 Hook events
| Event | When it triggers |
|---|---|
| PreToolUse | Before a tool call |
| PostToolUse | After a tool call |
| UserPromptSubmit | When the user sends a message (can inject additional context) |
| Stop | When the Agent is about to finish |
| SubagentStop | When a Sub-Agent finishes |
| Notification | When Claude Code is waiting for user input |
8.2 Cal's recommended Hook usage
- PreToolUse to block dangerous commands: When a bash command contains
rm -rf, pop up a notification or block it - PostToolUse for automatic linting: Automatically run
prettier --writeorpnpm lint - UserPromptSubmit injects context: Automatically appends the project's current git status to every question
- Stop auto commit: Automatically runs
git statuswhen a task ends, and prompts whether to commit - Notification pop-up alert: Sends a macOS notification when waiting for user input (using
osascript)
8.3 Cal's Personal Hooks
Cal's own hooks configuration (simplified version):
{
"hooks": {
"PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "~/.claude/hooks/block-dangerous.sh"}]}],
"PostToolUse": [{"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "~/.claude/hooks/auto-lint.sh"}]}],
"Stop": [{"hooks": [{"type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff"}]}]
}
}
The last Stop hook makes Claude Code play a beep — Cal said this lets him "focus on other things and look back only when he hears the sound".
9. MCP: Selection and Boundaries
MCP (Model Context Protocol) is a tool protocol standard launched by Anthropic. Cal gave selection recommendations.
9.1 When to Use MCP
- You need Claude Code to call an external API(GitHub, Slack, Jira, Notion)
- The API cannot be called directly with curl (requires auth, complex pagination)
- You will use this tool repeatedly (no need for one-off tools)
9.2 When Not to Use MCP
- Simple shell commands (just let Claude Code run bash directly)
- File system operations (built-in Read / Write / Edit)
- Web search (use WebFetch / WebSearch)
- One-off scripts (write a.sh file and let Claude Code run it)
9.3 Core MCPs Recommended by Cal
| MCP | Use case |
|---|---|
| github | issue / PR / review operations |
| playwright / chromium | Browser automation / E2E testing |
| postgres / sqlite | Database queries |
| filesystem(project-scoped) | Cross-directory file operations |
| brave-search | Replacement for WebSearch (more stable in some scenarios) |
9.4 MCP Anti-patterns
- Don't install a bunch of MCPs (each one takes up context and slows down startup)
- Don't make MCP tool descriptions too long (Cal has seen an MCP tool description that was 5000 tokens long)
- Don't use MCP as an "all-purpose assistant" (it is just a tool, not an Agent)
10. Cal's Personal Configuration Template
At the end of his talk, Cal shared his own Claude Code configuration (simplified version):
10.1 ~/.claude/CLAUDE.md(global)
# Cal's Global Preferences
- I prefer concise responses. Don't summarize what you just did unless I ask.
- When showing diffs, only show the changed lines, not full files.
- Use TypeScript over JavaScript when possible.
- Run tests before saying "done".
- If you encounter an error, fix the root cause, not the symptom.
- Never use `git push --force` without my explicit OK.
10.2 Project-level CLAUDE.md (example)
# Project: agent-framework
## Stack
- TypeScript + Node 20
- pnpm workspace
- Vitest for tests
- Biome for lint
## Commands
- `pnpm dev` — dev server
- `pnpm test` — vitest run
- `pnpm lint` — biome check + fix
- `pnpm typecheck` — tsc --noEmit
## Architecture
- `packages/core/` — runtime engine, no external deps
- `packages/cli/` — CLI entry, depends on core
- `packages/server/` — HTTP server (Hono)
## Conventions
- Files: kebab-case (agent-runner.ts)
- Types: PascalCase, exported from index.ts
- Internal helpers: prefix with _
- Tests next to source: agent-runner.test.ts
## Tradeoffs
- We prefer composition over inheritance.
- We avoid dependency injection frameworks — passing functions is enough.
10.3 Key Hooks
{
"hooks": {
"PostToolUse": [
{"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "pnpm biome format --write $CLAUDE_FILE_PATH"}]}
],
"Stop": [
{"hooks": [{"type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff"}]}
]
}
}
11. 5 "Gotchas" Emphasized by Cal
- Don't let Claude Code run
git pushwithout asking — even in AcceptEdits mode, push still requires confirmation by default - Commit before large refactors — you may not like the changes Claude Code makes halfway through; you can only reset if you have a checkpoint
- Don't use BypassPermissions on production repos — even if you "just want to take a look"
- Save key information before running /clear — Claude Code will forget all context
- Sub-Agents do not inherit the main Agent's CLAUDE.md — Sub-Agents start a new session and will re-read CLAUDE.md (so remember to put rules in the project-level file)
12. Comparison with Wang Kai's Claude Code Terminal Workflow Methodology (Full Version) comparison
| Dimension | Wang Kai's overview | newtype-cal talk (this wiki) |
|---|---|---|
| Perspective | Independent developer / product entrepreneur | Anthropic internal engineer |
| Focus | Multi-Agent orchestration / Subagent collaboration / Plan-driven | Single-Agent engineering / Hooks / Permissions |
| Tool stack | Claude Code + multi-browser matrix + MCP ecosystem | Claude Code + git + bash + a small number of MCPs |
| Task granularity | One complete product (several weeks) | One feature (several hours) |
| Sub-Agent philosophy | Primary reliance | Cautious use |
| Key insight | "The terminal window is the Agent" | "Agentic Search is better than RAG" |
Best practices:
- Independent developers: Read both; start with Cal's "single-Agent engineering" to build a foundation (get proficient with hooks / permissions / CLAUDE.md), then scale up with Wang Kai's "multi-Agent matrix"
- Anthropic-style projects: Primarily use Cal's methodology
- Multi-Agent matrix projects: Primarily use Wang Kai's methodology, with Cal's hooks / CLAUDE.md as the foundation
13. Reference List
- Cal Rueb's share at newtype Planet 2025-Q2 (source of this wiki)
- Anthropic official documentation: claude.com/docs/claude-code
- Related:Wang Kai's Claude Code Terminal Workflow Methodology (Full Version), Wang Kai's Multi-Agent Browser Matrix Architecture (v1.1 Practical Guide), newtype · MCP Protocol and Ecosystem in Practice, newtype · AI Coding Practice and Tool Stack Evolution
History
- 2026-05-16: Phase 3 ingest created from
10_Claude_Code_best_practices.md. Fully covers Cal's 12 core topics + personal configuration template + comparison with Wang Kai's overview.