| name | claude-code-patterns |
| description | Claude Code architecture — artifact design, context, agentic patterns. For CC audit/build. |
| allowed-tools | ["Read","Glob","Grep"] |
Claude Code Architecture Patterns
Reference patterns for designing effective Claude Code artifacts and understanding CC's internal architecture.
Quick Reference: Artifact Types
| Type | Layer | Purpose | Token Target | Quality Test |
|---|
| Agent | L1 Intent | Teach judgment + procedure | 150-400 lines | Completes task without clarification |
| Skill | L2 Context | Teach knowledge + reference | 150-250 lines (SKILL.md) | Answers 80% of routine questions |
| Rule | L3 Guardrails | Enforce boundaries | 50-150 lines | Zero violations in scope |
| Command | L4 Instructions | Orchestrate workflows | 50-150 lines | Predictable, verifiable output |
| Hook | L3 Guardrails | Deterministic prevention | 20-80 lines (JS) | 100% enforcement, no exceptions |
Agentic Architecture Patterns
The Agentic Loop
send → check stop_reason → execute tools → append → repeat
stop_reason == "end_turn" is the ONLY termination signal- Never parse text for "I'm done" (natural language termination)
- Never use arbitrary iteration caps (trust the model's signal)
- Claude returns text AND tool_use in the same response — check stop_reason, not content type
Multi-Agent Memory Isolation
Subagents do NOT share memory with coordinator or each other. All context must be passed explicitly via structured metadata (source URLs, doc names, page numbers).
Attention Dilution
14+ items in single pass → inconsistent depth. Fix: per-item analysis pass, then cross-item synthesis pass.
Session Management
| Strategy | When | Mechanism |
|---|
| Resume | Same task, no external changes | --resume |
| Fork | Explore alternative approach | Parallel worktrees |
| Fresh + Summary | Stale context, switching focus | New session + /wrapup notes |
Tool Design Patterns
Descriptions Are Selection Mechanism
Tool descriptions are for the MODEL, not humans. Include: what it does, inputs, example queries, boundaries vs similar tools.
4-5 Tool Limit Per Agent
18+ tools → <70% selection accuracy. Split into specialized subagents.
Error Categories
| Category | Retryable | Action |
|---|
| Transient | Yes | Wait and retry |
| Validation | After fix | Fix input, retry |
| Business | No | Alternative workflow |
| Permission | No | Escalate |
Distinguish access failure ("DB unreachable") from valid empty result ("no orders found").
Prompt Engineering Patterns
Explicit Criteria Beat Vague Instructions
"Be conservative" → fails intermittently. "Flag only when claimed behavior contradicts code" → reliable.
Few-Shot: 2-4 Examples with Reasoning
Include a "resist extraction" example (when NOT to act). Reasoning blocks teach generalization, not pattern matching.
Schema Design
"type": ["string", "null"] for optional fields (not "nullable": true)"unclear" enum value for genuine ambiguity"other" + detail field for extensible categories- Only
required fields that are always in the source — required = fabrication pressure
Validation-Retry Boundaries
Works for: format errors, structural errors, misplaced values.
Fails for: information not in source, fabrication, genuine ambiguity.
Context Management Patterns
Progressive Summarization Trap
Transactional data ($247.83, order #8891) gets compressed to "customer wants refund." Fix: persistent case facts block, never summarized.
Lost-in-the-Middle
Critical info at beginning/end of context. Middle gets less attention. Trim tool results to needed fields.
Hooks vs Prompts Decision
| Stakes | Enforcement |
|---|
| Money, security, compliance | Hook (100% deterministic) |
| Style, formatting, preferences | Prompt (~95% probabilistic) |
Token Efficiency Patterns
- Path-scope rules via YAML frontmatter globs (60-80% savings)
- Progressive disclosure in skills: SKILL.md summary vs full directory
- Agent descriptions under 120 chars (loaded on every selection)
- Commands are prompts (50-150 lines), not documentation
- Don't duplicate CLAUDE.md in rules — CLAUDE.md is always loaded
- Consolidate overlapping rules — one rule beats five saying similar things
Detailed Reference
- Sync Flow — Full sync-family protocol (loaded by sync-reviewer + coc-sync agents)
- Multi-CLI Migration — Loom's variant + emit pipeline reference
- SDK Upstream Donation — BUILD repo → loom → USE template flow
- Parallel Merge Workflow — Merging 5+ parallel worktree changes to the same file via specialist delegation
- Worktree Orchestration Protocol — Extended evidence + post-mortems for
rules/agents.md worktree MUSTs and rules/worktree-isolation.md
- Closure-Parity Specialist Discipline — BLOCKED-rationalization corpus + delegation-time detection signals + Origin evidence for
rules/agents.md § "MUST: Audit/Closure-Parity Verification Specialist Has Bash + Read"
- Workflow-Orchestration Throughput — CC how-to for
rules/governed-throughput.md + throttle-aware concurrency (rules/worktree-isolation.md Rule 4): read-only fan-out, verify→implement pipeline, schema returns, resumeFromRunId, the L2 curated-slice injection, the journal/0193 over-injection-degrades evidence
- Multi-Operator Coordination Substrate — full §1–§8 architecture + the 10 fold rules + MUST-4/5/6/7 substrate-integrity contracts + F-series forest registry for
rules/multi-operator-coordination.md (the always-on rule carries only the agent-facing behavioral contract)
- genesis-migration N=1 Org-Admin Anchor — enumerated sub-clauses + fold-time verification + BLOCKED corpus + sweep query for
rules/multi-operator-coordination.md MUST-7
- User-Flow Validation Walk Discipline — per-MUST DO/DO-NOT corpora + the full walk + scrub treatment + Origin for
rules/user-flow-validation.md (the always-on rule carries only the walk/receipts/scrub tripwires)
- Decision-Recording Discipline — decision-tree + ledger-signature-per-label + secrets fence + halt-and-report runbook for
rules/journal-author-discipline.md
- Redteam Dispatch Evidence Gate — errored/empty-is-zero-evidence + concurrency back-off for
rules/agents.md § "Redteam Reviewer Dispatch"
When to Use This Skill
- Creating a new agent, skill, rule, command, or hook
- Auditing existing artifacts for quality
- Optimizing token efficiency of the
.claude/ directory
- Understanding how CC components interact
Support
- cc-architect — Primary expert for CC artifact work
co-reference skill — CO methodology (principles, layers)co-reference skill — COC methodology (five-layer implementation)
