| name | claude-md-authoring |
| description | Creates and reviews CLAUDE.md configuration files for Claude Code. Applies HumanLayer guidelines including instruction budgets (~50 user-level, ~100 project-level), WHAT/WHY/HOW framework, and progressive disclosure. Identifies anti-patterns like using Claude as a linter for style rules. |
CLAUDE.md Authoring
Quickstart
- Determine scope: User-level (
~/.claude/) or project-level (.claude/)?
- Apply WHAT/WHY/HOW framework (project-level only)
- Keep instructions under budget: ~50 for user-level, ~100 for project-level
- Never use Claude as a linter: Style rules belong in tooling, not CLAUDE.md
- Validate with quality checklist before finalizing
Core Principle
"The only thing that the model knows about your codebase is the tokens you put into it."
CLAUDE.md is the highest-leverage point for context transfer. Every instruction competes for limited attention. Include only what Claude cannot infer and must apply universally.
Scope Decision
User-Level (~/.claude/CLAUDE.md)
Applies to ALL projects. Include only:
- Personal working style preferences
- Relationship dynamics (pushback, honesty, communication)
- Universal philosophy (YAGNI, root-cause debugging)
- Proactiveness boundaries
Never include:
- Project-specific commands (build, test, lint)
- Tech stack details
- Style rules that vary by project
- Tool/framework references that don't exist everywhere
Project-Level (.claude/CLAUDE.md)
Applies to ONE project. Use the WHAT/WHY/HOW framework: