claude-brain 0.30.2 → 0.30.3

package/src/hooks/claude-code-mastery.md

@@ -1,112 +1,112 @@
-# Claude Code Mastery Guidelines
-
-## Context Window = Your #1 Resource
-- Every file read, command output, and message eats context tokens. Performance **degrades** as it fills.
-- Track context usage mentally. When it feels heavy, act on it.
-- **Before auto-compaction hits:** proactively `/compact` with focus instructions ("focus on the API changes"), or start a fresh session with `--continue` for the same task or `--resume` to pick a named session.
-- When compaction triggers, early instructions get lost. Put persistent rules in CLAUDE.md, not conversation.
-- **Fork sessions** (`--fork-session`) to branch off and try risky approaches without polluting the original session.
-
-## Session Management — Use the Full Arsenal
-- **`/clear`** between unrelated tasks — stale context causes mistakes.
-- **`/rename auth-refactor`** your sessions — find them later with `claude --resume auth-refactor`.
-- **`/rewind` or Esc+Esc** — restore conversation, code, or both to any checkpoint. Every file edit is checkpointed.
-- **`/compact <focus>`** — manually compact with instructions on what to preserve.
-- **Esc+Esc → Summarize from here** — partial compaction that condenses only recent messages.
-- When approaching context limits: finish current subtask, commit, then start a **new session** referencing what was done. Fresh context > cluttered context.
-- **`--continue`** resumes last session. **`--resume`** opens picker. **`--from-pr 123`** resumes PR-linked sessions.
-- Sessions are independent — each starts fresh. Use CLAUDE.md and auto-memory for cross-session persistence.
-
-## Verification First — The #1 Leverage Point
-- **Always provide verification criteria before implementing.** Write failing test → implement → run test → confirm pass.
-- For UI: take screenshots (Chrome extension), compare to reference, list differences, iterate.
-- Never claim "fixed" or "done" without running the actual verification command and showing output.
-- Address root causes, not symptoms — don't suppress errors or add workarounds.
-
-## Explore → Plan → Implement → Verify
-- **Don't jump to coding.** Read relevant files first. Understand existing patterns.
-- **Plan mode** (Shift+Tab×2 or `--permission-mode plan`): read-only exploration, create plans, get approval before touching code.
-- **Ctrl+G** opens the plan in your editor for direct editing.
-- For multi-file changes: explore → plan → get approval → implement → verify.
-- For small/obvious fixes: skip planning, act directly.
-- After 2 failed attempts at the same fix: **stop, `/clear`, write a better prompt** incorporating what you learned. Don't retry.
-
-## Subagents — Separate Context, Clean Main Window
-- **Explore agent**: fast (Haiku), read-only, great for codebase search without bloating context.
-- **General-purpose agent**: full tools, complex multi-step operations.
-- **Plan agent**: research during plan mode.
-- Use subagents for: verbose output (test suites, logs), research/investigation, code review (fresh eyes, no author bias).
-- Keep in main conversation when: frequent back-and-forth needed, context is shared across phases.
-- **Background subagents** (Ctrl+B): run concurrently while you keep working. Resume with agent ID if they fail.
-- **Chain subagents**: reviewer finds issues → optimizer fixes them. Each gets clean context.
-- **Parallel research**: "investigate auth, database, and API modules in parallel using separate subagents."
-- Custom subagents in `.claude/agents/` — specialized roles with restricted tools, specific models, and scoped permissions.
-
-## Tool Usage — Precision Over Convenience
-- **Dedicated tools always**: Read/Edit/Write/Glob/Grep — never bash cat/sed/grep/find.
-- **Parallel tool calls**: independent operations in the same message. Sequential only when dependent.
-- **`gh` CLI** for GitHub (PRs, issues, comments) — unauthenticated API hits rate limits.
-- **`@file`** references load file content directly — faster than searching.
-- **Pipe data**: `cat error.log | claude -p "explain this"` — Unix composability.
-- **`--output-format json`** for structured output in scripts.
-- **`--allowedTools`** to scope permissions for batch operations.
-
-## MCP — External Tools & Data Sources
-- MCP servers add tool definitions to **every request** — each server costs context tokens.
-- Use `/mcp` to check per-server costs and authenticate with OAuth servers.
-- MCP Tool Search auto-activates when tools exceed 10% of context window.
-- `@server:resource` to reference MCP resources inline (like `@github:issue://123`).
-- MCP tool output > 10K tokens triggers warning — set `MAX_MCP_OUTPUT_TOKENS` if needed.
-
-## Skills — On-Demand Knowledge
-- Skills load descriptions at startup but full content loads only when invoked — efficient for context.
-- `/skill-name` for direct invocation. Claude auto-invokes when description matches.
-- `context: fork` runs skill in isolated subagent — good for tasks that produce verbose output.
-- `$ARGUMENTS` placeholder for dynamic input. `!`command`` for dynamic context injection.
-- `disable-model-invocation: true` for manual-only triggers (deploy, commit).
-
-## Hooks — Deterministic Automation
-- Hooks fire at lifecycle points — they're guaranteed, not advisory like CLAUDE.md instructions.
-- **PreToolUse**: validate/block/modify tool calls before execution.
-- **PostToolUse**: lint, format, or react after file edits.
-- **Stop**: enforce quality gates before Claude finishes (tests must pass, etc.).
-- **SessionStart**: inject context, set environment variables.
-- **UserPromptSubmit**: add context or block prompts.
-- Async hooks (`"async": true`) run in background without blocking.
-
-## Communication & Prompting
-- Reference `file:line` for code locations. Show diffs, not walls of explanation.
-- Ask **one focused question** when stuck, not a list of 10.
-- If told "fix it" — investigate, diagnose, implement, verify. Don't ask what to fix.
-- Be specific: name files, mention constraints, point to example patterns.
-- For big features: "Interview me using AskUserQuestion. Ask about edge cases, tradeoffs, and the hard parts I haven't considered."
-- Vague prompts are fine for exploration. Specific prompts for implementation.
-
-## Git Worktrees — True Parallel Isolation
-- `git worktree add ../project-feature -b feature` — separate directory, isolated files, shared history.
-- Run independent Claude sessions in each worktree — no interference.
-- Perfect for: writer/reviewer pattern, parallel feature development, risky experiments.
-- `git worktree list` to see all, `git worktree remove` when done.
-
-## Headless Mode — CI/CD & Automation
-- `claude -p "prompt"` — non-interactive, single-shot execution.
-- `--output-format stream-json` for real-time processing.
-- `--dangerously-skip-permissions` in sandboxed containers only.
-- Fan out: loop through file list calling `claude -p` for each with `--allowedTools` scoping.
-
-## Anti-Patterns — Recognize and Fix Fast
-- **Kitchen sink session**: mixing unrelated tasks → `/clear` between them.
-- **Correction loop**: 2+ failed corrections → `/clear`, rewrite prompt with lessons learned.
-- **Trust gap**: plausible-looking code without verification → always run tests/lint/typecheck.
-- **Infinite exploration**: unbounded investigation filling context → scope narrowly or use subagents.
-- **Over-engineering**: adding features/handlers/abstractions beyond what's asked → solve exactly what's requested.
-- **Context amnesia**: important rules from early in session lost after compaction → put them in CLAUDE.md.
-- **Guessing**: assuming file contents or structure → Read the code before modifying.
-
-## CLAUDE.md — Persistent Memory That Survives Sessions
-- **Only include what Claude can't infer from code.** Bash commands, code style deviations, workflow rules.
-- **Keep it short.** If Claude already does something correctly without the instruction, delete it.
-- Use emphasis ("IMPORTANT", "YOU MUST") for critical rules — improves adherence.
-- `@path/to/import` syntax to import other files. Relative paths resolve from the importing file.
-- `.claude/rules/*.md` for modular, topic-specific rules. Support `paths:` frontmatter for file-scoped rules.
-- Auto-memory (`~/.claude/projects/<project>/memory/`) — Claude's own notes, first 200 lines of MEMORY.md loaded per session.
+# Claude Code Mastery Guidelines
+
+## Context Window = Your #1 Resource
+- Every file read, command output, and message eats context tokens. Performance **degrades** as it fills.
+- Track context usage mentally. When it feels heavy, act on it.
+- **Before auto-compaction hits:** proactively `/compact` with focus instructions ("focus on the API changes"), or start a fresh session with `--continue` for the same task or `--resume` to pick a named session.
+- When compaction triggers, early instructions get lost. Put persistent rules in CLAUDE.md, not conversation.
+- **Fork sessions** (`--fork-session`) to branch off and try risky approaches without polluting the original session.
+
+## Session Management — Use the Full Arsenal
+- **`/clear`** between unrelated tasks — stale context causes mistakes.
+- **`/rename auth-refactor`** your sessions — find them later with `claude --resume auth-refactor`.
+- **`/rewind` or Esc+Esc** — restore conversation, code, or both to any checkpoint. Every file edit is checkpointed.
+- **`/compact <focus>`** — manually compact with instructions on what to preserve.
+- **Esc+Esc → Summarize from here** — partial compaction that condenses only recent messages.
+- When approaching context limits: finish current subtask, commit, then start a **new session** referencing what was done. Fresh context > cluttered context.
+- **`--continue`** resumes last session. **`--resume`** opens picker. **`--from-pr 123`** resumes PR-linked sessions.
+- Sessions are independent — each starts fresh. Use CLAUDE.md and auto-memory for cross-session persistence.
+
+## Verification First — The #1 Leverage Point
+- **Always provide verification criteria before implementing.** Write failing test → implement → run test → confirm pass.
+- For UI: take screenshots (Chrome extension), compare to reference, list differences, iterate.
+- Never claim "fixed" or "done" without running the actual verification command and showing output.
+- Address root causes, not symptoms — don't suppress errors or add workarounds.
+
+## Explore → Plan → Implement → Verify
+- **Don't jump to coding.** Read relevant files first. Understand existing patterns.
+- **Plan mode** (Shift+Tab×2 or `--permission-mode plan`): read-only exploration, create plans, get approval before touching code.
+- **Ctrl+G** opens the plan in your editor for direct editing.
+- For multi-file changes: explore → plan → get approval → implement → verify.
+- For small/obvious fixes: skip planning, act directly.
+- After 2 failed attempts at the same fix: **stop, `/clear`, write a better prompt** incorporating what you learned. Don't retry.
+
+## Subagents — Separate Context, Clean Main Window
+- **Explore agent**: fast (Haiku), read-only, great for codebase search without bloating context.
+- **General-purpose agent**: full tools, complex multi-step operations.
+- **Plan agent**: research during plan mode.
+- Use subagents for: verbose output (test suites, logs), research/investigation, code review (fresh eyes, no author bias).
+- Keep in main conversation when: frequent back-and-forth needed, context is shared across phases.
+- **Background subagents** (Ctrl+B): run concurrently while you keep working. Resume with agent ID if they fail.
+- **Chain subagents**: reviewer finds issues → optimizer fixes them. Each gets clean context.
+- **Parallel research**: "investigate auth, database, and API modules in parallel using separate subagents."
+- Custom subagents in `.claude/agents/` — specialized roles with restricted tools, specific models, and scoped permissions.
+
+## Tool Usage — Precision Over Convenience
+- **Dedicated tools always**: Read/Edit/Write/Glob/Grep — never bash cat/sed/grep/find.
+- **Parallel tool calls**: independent operations in the same message. Sequential only when dependent.
+- **`gh` CLI** for GitHub (PRs, issues, comments) — unauthenticated API hits rate limits.
+- **`@file`** references load file content directly — faster than searching.
+- **Pipe data**: `cat error.log | claude -p "explain this"` — Unix composability.
+- **`--output-format json`** for structured output in scripts.
+- **`--allowedTools`** to scope permissions for batch operations.
+
+## MCP — External Tools & Data Sources
+- MCP servers add tool definitions to **every request** — each server costs context tokens.
+- Use `/mcp` to check per-server costs and authenticate with OAuth servers.
+- MCP Tool Search auto-activates when tools exceed 10% of context window.
+- `@server:resource` to reference MCP resources inline (like `@github:issue://123`).
+- MCP tool output > 10K tokens triggers warning — set `MAX_MCP_OUTPUT_TOKENS` if needed.
+
+## Skills — On-Demand Knowledge
+- Skills load descriptions at startup but full content loads only when invoked — efficient for context.
+- `/skill-name` for direct invocation. Claude auto-invokes when description matches.
+- `context: fork` runs skill in isolated subagent — good for tasks that produce verbose output.
+- `$ARGUMENTS` placeholder for dynamic input. `!`command`` for dynamic context injection.
+- `disable-model-invocation: true` for manual-only triggers (deploy, commit).
+
+## Hooks — Deterministic Automation
+- Hooks fire at lifecycle points — they're guaranteed, not advisory like CLAUDE.md instructions.
+- **PreToolUse**: validate/block/modify tool calls before execution.
+- **PostToolUse**: lint, format, or react after file edits.
+- **Stop**: enforce quality gates before Claude finishes (tests must pass, etc.).
+- **SessionStart**: inject context, set environment variables.
+- **UserPromptSubmit**: add context or block prompts.
+- Async hooks (`"async": true`) run in background without blocking.
+
+## Communication & Prompting
+- Reference `file:line` for code locations. Show diffs, not walls of explanation.
+- Ask **one focused question** when stuck, not a list of 10.
+- If told "fix it" — investigate, diagnose, implement, verify. Don't ask what to fix.
+- Be specific: name files, mention constraints, point to example patterns.
+- For big features: "Interview me using AskUserQuestion. Ask about edge cases, tradeoffs, and the hard parts I haven't considered."
+- Vague prompts are fine for exploration. Specific prompts for implementation.
+
+## Git Worktrees — True Parallel Isolation
+- `git worktree add ../project-feature -b feature` — separate directory, isolated files, shared history.
+- Run independent Claude sessions in each worktree — no interference.
+- Perfect for: writer/reviewer pattern, parallel feature development, risky experiments.
+- `git worktree list` to see all, `git worktree remove` when done.
+
+## Headless Mode — CI/CD & Automation
+- `claude -p "prompt"` — non-interactive, single-shot execution.
+- `--output-format stream-json` for real-time processing.
+- `--dangerously-skip-permissions` in sandboxed containers only.
+- Fan out: loop through file list calling `claude -p` for each with `--allowedTools` scoping.
+
+## Anti-Patterns — Recognize and Fix Fast
+- **Kitchen sink session**: mixing unrelated tasks → `/clear` between them.
+- **Correction loop**: 2+ failed corrections → `/clear`, rewrite prompt with lessons learned.
+- **Trust gap**: plausible-looking code without verification → always run tests/lint/typecheck.
+- **Infinite exploration**: unbounded investigation filling context → scope narrowly or use subagents.
+- **Over-engineering**: adding features/handlers/abstractions beyond what's asked → solve exactly what's requested.
+- **Context amnesia**: important rules from early in session lost after compaction → put them in CLAUDE.md.
+- **Guessing**: assuming file contents or structure → Read the code before modifying.
+
+## CLAUDE.md — Persistent Memory That Survives Sessions
+- **Only include what Claude can't infer from code.** Bash commands, code style deviations, workflow rules.
+- **Keep it short.** If Claude already does something correctly without the instruction, delete it.
+- Use emphasis ("IMPORTANT", "YOU MUST") for critical rules — improves adherence.
+- `@path/to/import` syntax to import other files. Relative paths resolve from the importing file.
+- `.claude/rules/*.md` for modular, topic-specific rules. Support `paths:` frontmatter for file-scoped rules.
+- Auto-memory (`~/.claude/projects/<project>/memory/`) — Claude's own notes, first 200 lines of MEMORY.md loaded per session.