Skip to main content

Best Practices

What separates a config that compounds from one that stagnates?

Ten principles distilled from running Claude Code across two repos, 14 rules, 30 hooks, 45 skills, and 32 agents.

1. Structure over discipline. If it matters, enforce it structurally. Rules are suggestions. Hooks are guarantees. Generators make violations impossible.

2. Pair rules with hooks. Every rule that's been violated under cognitive load now has a hook. The pattern: rule defines the standard, hook catches violations. Neither works alone.

3. PostToolUse for validation, PreToolUse for blocking. You validate what changed (Post). You block what shouldn't happen (Pre). Don't use PreToolUse for validation — you don't know what will change yet.

4. Separate judgment from computation. LLMs score. Scripts rank. Agents draft. Validators review. The builder never validates their own work. This is commissioning applied to code.

5. Skills need evidence gates. "All pass" without line numbers is a red flag. Quote the evidence or don't claim the gate passed. A skill invoked but not followed creates false confidence.

6. Keep CLAUDE.md thin. Router, not repository. Import rules with @, don't inline them. If Claude ignores instructions, the file is too long.

7. Single source of truth. .ai/rules/ is real. .claude/rules/ is symlinks. Edit once, every agent sees the change. Never maintain two copies of the same rule.

8. Match model to task. Opus for architecture. Sonnet for execution. Haiku for quick fixes. Use model in agent/skill frontmatter to override per-task.

9. Isolate dangerous work. isolation: worktree for agents that might break things. Deny lists for repos you shouldn't write to. Separate settings.json (production) from settings.local.json (session flexibility).

10. Memory is for patterns, not sessions. Save stable conventions confirmed across multiple interactions. Delete outdated memories. Keep MEMORY.md under 200 lines.

Context​

  • Config Architecture — components, enforcement hierarchy, two-repo config
  • OODA Loop — daily/weekly/monthly cadence for keeping config current
  • Innovators — practitioners applying these principles at the edge
  • Tools — the tool-calling layer where judgment meets computation

Questions​

Which of these ten principles is your weakest point today?

  • If rules without hooks are suggestions — how many of your current rules have no paired hook?
  • What judgment call do you make every session that could become a structural enforcement?
  • When was the last time you deleted a rule, skill, or hook that wasn't being followed?