A Claude Code subagent and best practices guide for turning lessons, corrections, and workflows into the right .claude/ artifacts.
Every Claude Code user builds up knowledge — corrections, workflow patterns, project conventions — that gets lost between sessions. You know you should codify it somewhere in .claude/, but with rules, skills, hooks, commands, subagents, and CLAUDE.md all available, it's not obvious which one to use. The coach agent makes that decision for you and writes the file.
A custom subagent that helps you decide where something belongs in your Claude Code setup. Tell it what you want to codify — a gotcha, a workflow, a convention — and it will:
- Read your current
.claude/configuration - Recommend the right artifact type (CLAUDE.md entry, rule, skill, command, hook, subagent, or settings change)
- Draft the content
- Create the file in the right location
A comprehensive guide covering all major Claude Code configuration surfaces, synthesized from the shanraisshan/claude-code-best-practice repo, Anthropic team tips, and community knowledge. The coach agent uses this as its reference material.
Topics covered:
- CLAUDE.md structure and loading behavior
- Rules folder with path-scoped activation
- Verification and feedback loops (2-3x quality improvement)
- Plan mode workflow
- Parallel worktrees
- Context management
- Custom commands, skills, subagents, and hooks
- Settings, permissions, and MCP servers
- Model and effort optimization
- Prompting techniques and CLI flags
- Claude Code installed and authenticated
# Clone the repo
git clone https://github.com/jonathanlesh/claude-code-coach.git
# Run the install script
cd claude-code-coach
bash install.sh- Copy the agent definition to your global agents directory:
mkdir -p ~/.claude/agents
cp agents/claude-coach.md ~/.claude/agents/- Copy the best practices reference doc:
mkdir -p ~/.claude/agent_docs
cp docs/claude-code-best-practices.md ~/.claude/agent_docs/Once installed, the coach agent is available in any Claude Code session. Claude will invoke it when your request matches the agent's description — asking to codify a pattern, set up a hook, create a rule, etc. You can also reference it directly:
Help me turn this into a rule: "Always use snake_case for Python files in src/api/"
I keep forgetting to run tests before committing. Can you set up a hook for that?
How should I structure my CLAUDE.md for a monorepo?
What's the best way to add a custom command for PR reviews?
The coach agent follows a decision framework to route your request to the right artifact:
| Signal | Artifact |
|---|---|
| Claude keeps making the same mistake | Gotcha in CLAUDE.md or a rule |
| Correction about a specific framework/file type | Path-scoped rule |
| Workflow done 3+ times per day | Skill or command |
| Task domain needing isolated tools/model | Subagent |
| Something that should happen on a lifecycle event | Hook |
| Tool/command that should run without prompts | Permission rule |
Contributions welcome! If you've found patterns that work well for your Claude Code setup, open a PR. Especially interested in:
- Additional decision framework heuristics
- New best practices or tips
- Corrections or updates as Claude Code evolves
- Example configurations for common workflows
Remove the two installed files:
rm ~/.claude/agents/claude-coach.md
rm ~/.claude/agent_docs/claude-code-best-practices.mdMIT