| name | codification-reference |
| description | Reference guide to all mechanisms for codifying behaviors, lessons, and guardrails — skills, subagents, hooks, tests, linters, scripts, and more. Trigger phrases: "what mechanism should I use", "how do I codify this", "where should this live", "what are my options for enforcing". |
| last-reviewed | "2026-03-26T00:00:00.000Z" |
Codification Reference
Overview
A reference guide to the full toolkit of mechanisms for codifying behaviors,
lessons, and guardrails so they are enforced going forward. Covers both
Claude-specific mechanisms (skills, subagents, hooks, CLAUDE.md, memories) and
general development mechanisms (tests, linters, CI steps, scripts, cron jobs,
CLI tools).
Use this when deciding where a lesson, convention, or behavior should live —
and how strongly it should be enforced.
When to Use
- Choosing how to persist a lesson from a debrief
- Designing a new augmentation (hook, skill, subagent, etc.)
- Deciding whether something belongs in a test, a linter rule, CLAUDE.md, etc.
- Evaluating whether an existing codification is at the right level of strength
- Building a new automation and choosing the right tool
Selection Principles
- Prefer mechanical enforcement over convention. A linter rule beats a
memory. A test beats a comment. A hook beats a preference you have to
remember. A script beats a set of manual steps.
- Script what's mechanical. Wherever a process has deterministic steps —
even within a skill that also requires judgment — extract those steps into a
script. Skills should handle edge cases and judgment; scripts should handle
the predictable parts.
- Scope tightly. A project-level rule beats a global one when the lesson
is project-specific. A subagent with specific skills beats loading
everything into every session. Install at the narrowest scope that covers
the need.
- Discuss tradeoffs explicitly. If the right mechanism isn't obvious,
surface the tradeoffs rather than prematurely proposing based on
uncommunicated assumptions. Design decisions always involve tradeoffs.
- Strongest doesn't mean heaviest. A one-line linter rule that catches a
pattern mechanically is stronger than a complex skill that requires judgment
— even though the skill is "more work."
Mechanism Overview
Tier 1: Mechanical Enforcement
These run automatically and catch violations without human attention.
| Mechanism | What it does | Scope | When to use |
|---|
| Test | Asserts an invariant in CI | Per-project | A specific behavior must hold; a regression was found |
| Linter / static analysis | Flags a pattern mechanically | Project or global | A code pattern should always be flagged |
| Pre-commit hook (git) | Blocks commits violating a rule | Per-project | A constraint that should never reach the repo |
| CI step | Enforces a check in the pipeline | Per-project | A property of the built/packaged artifact must hold |
| Script | Automates a deterministic process | Any | A task can be completed without human judgment |
| Cron job | Runs a script on a schedule | System or CI | A check or process needs to run at regular intervals |
Tier 2: Agent Directives
These govern agent behavior in relevant sessions. The agent follows
instructions rather than mechanical enforcement catching violations.
| Mechanism | What it does | Scope | When to use |
|---|
| CLAUDE.md (project) | Project-specific instructions | Per-project | Conventions, constraints, and context for this codebase |
| CLAUDE.md (global) | Global instructions | All sessions | Behavioral directives that apply everywhere |
| AGENTS.md | Instructions for all AI agents | Per-project | Multi-agent contexts (Cursor, Codex, etc.) |
| Skill (3 modes) | Reusable knowledge or workflow | Global or per-project | See skill modes below |
| Subagent | Scoped agent with specific tools/skills | Global or per-project | A role that should only activate for matching tasks |
| Plugin | Bundled package of skills, hooks, agents | Installable at any scope | Distributing a cohesive set of capabilities |
| Claude hook | Runs on Claude Code events | Global or per-project | "When Claude does X, automatically do Y" |
| MCP server | Exposes external tools to the agent | Global or per-project | Agent needs access to an external system's API |
Tier 3: Context
These inform behavior but don't enforce or direct it.
| Mechanism | What it does | Scope | When to use |
|---|
| Memory (feedback) | Records a correction or validated approach | Per-project or global | A preference that can't be codified as a rule |
| Memory (user) | Records who the user is | Global | Tailoring responses to user expertise/role |
| Memory (project) | Records project context | Per-project | Non-obvious project lore not in code or docs |
| Memory (reference) | Points to external resources | Per-project or global | Bookmarking where to find information |
| Documentation | READMEs, ADRs, inline comments | Per-project | Helping future readers understand non-obvious decisions |
Tier 4: Tracking
These don't enforce anything but ensure follow-up happens.
| Mechanism | What it does | Scope | When to use |
|---|
| Issue / TODO | Tracks work to be done | Per-project | Needs follow-up but shouldn't block now |
| Template / snippet | A reusable pattern to scaffold | Global or per-project | A pattern worth formalizing for future use |
Skill Modes
Skills replaced legacy commands (.claude/commands/) and support three
invocation modes controlled by frontmatter flags:
| Mode | Frontmatter | Who invokes | Use for |
|---|
| Default | (none) | User or Claude auto-triggers | Reference content, workflows Claude should use when relevant |
| User-only | disable-model-invocation: true | User only | Action workflows with side effects you want to control |
| Background | user-invocable: false | Claude only | Context Claude should know but users wouldn't invoke |
Skills can include supporting files (scripts, references, templates) in their
directory. Skill descriptions are always in context (~2% of context budget);
full content loads on demand when invoked.
→ Deep dive: references/skills-and-subagents.md
→ Official docs: https://code.claude.com/docs/en/skills.md
Hooks
Three distinct hook systems serve different purposes:
| Hook type | Trigger | Config location | Use for |
|---|
| Claude hooks | Claude Code events (PreToolUse, PostToolUse, etc.) | settings.json | Automating behavior around Claude's actions |
| Git hooks | Git events (pre-commit, pre-push, etc.) | .git/hooks/ or .husky/ | Enforcing code quality before commits/pushes |
| Cursor hooks | Cursor editor events | .cursor/ config | Cursor-specific automation |
Claude hooks and git hooks are complementary — Claude hooks govern agent
behavior, git hooks govern repository integrity.
→ Deep dive: references/hooks.md
→ Official docs: https://code.claude.com/docs/en/hooks.md
Scripts vs Skills vs MCP vs CLI Tools
When automating a capability, choose the right vehicle:
| Vehicle | When to use | When NOT to use |
|---|
| Script | Deterministic process, no judgment needed | Requires context-dependent decisions |
| Skill | Requires AI judgment, edge case handling | Entirely mechanical — script it instead |
| MCP server | Agent needs live access to an external system's API | A CLI tool already provides the same access |
| CLI tool | Standalone utility usable by humans and agents | Only useful within an agent context |
A skill can (and should) call scripts for its mechanical parts. A CLI tool is
often preferable to an MCP server because it works for both humans and agents
and doesn't require MCP infrastructure.
→ Deep dive: references/automation.md
→ Official docs (MCP): https://code.claude.com/docs/en/mcp.md
Decision Process
When you have something to codify:
- Can it be caught mechanically? → Test, linter rule, CI step, hook,
script
- Is it a behavioral directive for an agent? → CLAUDE.md, subagent, skill,
or plugin
- Is it context that informs judgment? → Memory or documentation
- Does it need follow-up work? → Issue or TODO
Within each tier, scope as tightly as possible — project over global, specific
subagent over always-loaded skill, targeted test over broad documentation.
When a mechanism spans tiers (e.g., a skill that calls a script), use the
strongest tier for the mechanical parts and the appropriate tier for the
judgment parts.
Keeping This Reference Current
The Claude Code ecosystem evolves rapidly. When using this reference:
- Verify mechanisms against current docs before recommending them —
features may have been added, renamed, or deprecated since last review
- Update this document when you discover a new mechanism, a changed
behavior, or a gap
- Check the
last-reviewed date in frontmatter — if stale, prioritize
verification over recall
External Documentation
