codification-reference

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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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:

1. Can it be caught mechanically? → Test, linter rule, CI step, hook, script
2. Is it a behavioral directive for an agent? → CLAUDE.md, subagent, skill, or plugin
3. Is it context that informs judgment? → Memory or documentation
4. 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

Topic	URL
Skills	https://code.claude.com/docs/en/skills.md
Subagents	https://code.claude.com/docs/en/sub-agents.md
Plugins	https://code.claude.com/docs/en/plugins.md
Claude hooks	https://code.claude.com/docs/en/hooks.md
CLAUDE.md and memory	https://code.claude.com/docs/en/memory.md
MCP servers	https://code.claude.com/docs/en/mcp.md
Settings and permissions	https://code.claude.com/docs/en/settings.md
Commands (legacy)	https://code.claude.com/docs/en/commands.md