Claude Code Patterns (CC)

CC (Claude Code) is the set of universal patterns for structuring AI-assisted work using Claude Code’s artifact system. It defines how to build agents, skills, rules, hooks, commands, and settings that make any Claude Code session disciplined rather than ad-hoc.

CC is not a product or a framework. It is a collection of conventions and quality rules for the seven artifact types that Claude Code supports. Any project that adopts CC gets consistent behavior across sessions, enforceable guardrails, and knowledge that compounds instead of evaporating when the context window resets.

CC is developed at co/ (the CO artifact management repo) and distributed to all downstream repos: the COC templates for codegen, the CO template for new domain applications, and every domain application (co-research, co-finance, co-education, etc.).

The seven artifact types

Claude Code recognizes seven artifact types. Each has a specific role and specific quality constraints.

1. Agents

Location: .claude/agents/

Specialized AI personas with domain knowledge. An agent file defines a system prompt that shapes Claude’s behavior for a particular task category. When you invoke an agent, Claude adopts that persona’s expertise, constraints, and workflow.

Quality rules:

• Description field under 120 characters, with trigger phrases (“Use when…”, “Use for…”)
• File under 400 lines total
• No knowledge dumps: reference material goes in skills, not inline

Why these constraints matter: Agent descriptions load into every agent-selection decision. Long descriptions waste tokens on every turn. Embedded reference material competes with the actual task in the context window.

2. Skills

Location: .claude/skills/

Reference knowledge organized for progressive disclosure. A skill directory contains a SKILL.md index file and optional sub-files with deeper reference. Claude reads SKILL.md first and only reads sub-files when the question demands it.

Quality rules:

• SKILL.md answers 80% of routine questions without requiring sub-file reads
• Quick-reference tables and key patterns go in the index
• Deep reference (API details, edge cases, examples) goes in sub-files

Why this structure matters: Every sub-file read is a tool call. A skill that requires five reads to answer a basic question is five times slower than one with a good index.

3. Rules

Location: .claude/rules/

Behavioral guardrails enforced through soft guidance. Rules shape how Claude approaches work: coding standards, communication style, domain constraints. Claude follows rules because they are in context, not because a mechanism prevents violation.

Quality rules:

• Every rule includes DO/DO NOT examples showing both correct and incorrect patterns
• Every rule includes a “Why” rationale explaining the reasoning
• Path-scoped with YAML frontmatter globs where possible (a SQL rule should not load when editing CSS)

Why rationale matters: Without a “Why” line, Claude interprets rules differently each session. Rationale enables applying the spirit of the rule in edge cases.

4. Hooks

Location: scripts/hooks/

Deterministic enforcement scripts that run outside the model. Hooks fire on specific triggers (every user message, before commit, on session start) and execute JavaScript or shell code. Unlike rules, hooks cannot be forgotten or reinterpreted. They are hard enforcement.

Quality rules:

• Every hook includes a setTimeout fallback that returns { continue: true } and exits
• No semantic analysis via regex (hooks check structure, not meaning)
• Defense-in-depth: critical rules get hook enforcement in addition to rule files

Why timeout handling is required: A hanging hook blocks the entire Claude Code session indefinitely. The timeout fallback ensures the session continues even if processing stalls.

5. Commands

Location: .claude/commands/

Structured workflow invocations. A command file defines a prompt that injects as a user message when invoked via /command-name. Commands are how you package repeatable workflows: /analyze, /plan, /implement, /review.

Quality rules:

• Under 150 lines
• Move reference material to skills (commands inject as user messages and compete with actual user intent in the token budget)

6. Settings

Location: .claude/settings.json

Tool permissions, hook configuration, and MCP server declarations. Settings control what Claude can do (which tools are allowed), what runs automatically (which hooks fire on which triggers), and what external services are available (MCP servers).

7. CLAUDE.md

Location: Project root

The master directive loaded every session. CLAUDE.md is always in context. It sets the project identity, lists available commands, defines the artifact tier structure, and points to key resources. Everything in CLAUDE.md pays its token cost on every turn.

Quality rules:

• Do not restate rules that exist in .claude/rules/ (they load separately)
• Do not embed reference material that belongs in skills

Key CC patterns

Progressive disclosure

Not all knowledge needs to load on every turn. CC organizes information in layers:

Layer	What loads	Typical size
CLAUDE.md	Every turn, always	Under 200 lines
SKILL.md indexes	When a skill is referenced	10-50 lines
Topic files	When the index does not have enough detail	50-250 lines
Deep reference	On demand, when specific questions arise	Unlimited

This keeps the context window focused on the current task while making deep knowledge available when needed.

Defense in depth

For rules that absolutely cannot be violated, CC uses multiple independent enforcement layers:

1. CLAUDE.md states the rule (always in context)
2. Dedicated rule file provides full detail with examples and rationale
3. Anti-amnesia hook re-injects the rule every user message
4. Session-start hook establishes the rule at the beginning of every session
5. Validation hook checks outputs before they reach the user

Five layers. If any single layer fails (context compression drops CLAUDE.md, a rule file is not loaded for the current path), the other four still enforce the constraint.

Anti-amnesia

A hook that fires on every user message and re-injects critical rules fresh into the context. This solves the fundamental problem of long conversations: as the context window fills and older content gets compressed, important rules can fade. The anti-amnesia hook runs outside the model’s memory, so it survives compression. Every message, the rules come back at full fidelity.

Framework-first

Before writing anything from scratch, check whether existing building blocks handle the task. Composition over creation. In the Kailash ecosystem, this means checking 188 workflow nodes before building a custom one. In any CC project, it means checking existing agents, skills, and commands before creating new ones.

CC quality rules summary

These rules apply when creating or modifying any CC artifact:

Rule	Why
Agent descriptions under 120 characters with trigger phrases	Descriptions load into every agent-selection decision
Skills follow progressive disclosure (SKILL.md answers 80%)	Minimizes tool calls for routine questions
Rules include DO/DO NOT examples	Anchors consistent behavior across sessions
Rules include “Why” rationale	Enables applying the spirit of the rule in edge cases
Commands under 150 lines	Commands inject as user messages; long commands compete with user intent
Hooks include timeout handling	Prevents hanging the entire session
Agents under 400 lines, no knowledge dumps	Agent context competes with task context
No duplicating CLAUDE.md in skills or rules	CLAUDE.md is always loaded; duplicating it doubles token cost
Path-scope rules that apply to specific file types	A SQL rule loading when editing CSS is waste

How CC relates to CO and COC

CC, CO, and COC are three distinct layers:

• CC is the universal tool-level patterns. How to build Claude Code artifacts that work well. Applies to any project using Claude Code, regardless of domain.
• CO (Cognitive Orchestration) is the methodology. How to structure human-AI collaboration: eight principles, five-layer architecture, six-phase workflow. CO is domain-agnostic. See the CO specification.
• COC is CC + CO applied to software development. The codegen application. COC adds domain-specific agents (database specialists, API builders, testing frameworks), domain-specific skills (SDK reference, framework patterns), and domain-specific commands (/implement, /deploy). See the COC quickstart.

The artifact flow:

co/ ──CC+CO artifacts──→ co-template ──→ domain repos (research, finance, education, ...)
                    └──→ kailash/    ──→ COC templates ──→ codegen projects

CC patterns originate at co/ and flow outward. Domain repos add their own domain-specific artifacts on top of the CC foundation. They never modify CC artifacts directly; improvements flow upstream through co/.

Reference implementation

The Kailash ecosystem (github.com/terrene-foundation) is the reference implementation of CC at scale:

Artifact type	Scale
Agents	50+ across 7 categories (architecture, implementation, testing, review, deployment, domain, management)
Skills	31 directories with 600+ reference files
Rules	28 rule files with defense-in-depth enforcement
Hooks	8 hooks including the anti-amnesia mechanism
Commands	30 commands implementing the six-phase workflow

The COC template repository packages all of these into a single starting point for new projects.

Getting started

Build a new domain application. Clone the CO template and configure it for your domain. The template has the CC artifact structure pre-built; you add domain-specific agents, skills, and rules.

Build software with COC. See the COC quickstart. Clone the COC template, run claude, type /start.

Understand the methodology. Read the CO specification for the eight principles, five-layer architecture, and six-phase workflow that CC implements at the tooling level.

Inspect the reference implementation. Browse kailash-coc-claude-py to see CC artifacts in production: how agents reference skills, how rules enforce standards, how hooks provide defense-in-depth, and how commands orchestrate the phased workflow.