| name | t1k:architecture |
| description | Design and review agentic systems against Claude Code architecture canon — agent loops, tool interfaces, prompt-cache strategy, MCP/hooks/memory primitives, CLI vs Agent SDK. |
| keywords | ["architecture","agent loop","prompt cache","fork agent","subagent","MCP","tool interface","hooks","memory system","agent SDK","claude-code","design canon","review checklist"] |
| argument-hint | [design or review topic] |
| effort | medium |
| version | 1.94.2 |
| origin | theonekit-core |
| repository | The1Studio/theonekit-core |
| module | t1k-extended |
| protected | true |
Claude Code Architecture — Design & Review Skill
Canon for designing/reviewing agentic systems, distilled from an 18-chapter reverse-engineering of Anthropic's Claude Code CLI.
When to use
- Designing an agent loop, sub-agent system, tool interface, memory system, hooks/extension model, prompt-cache strategy, or remote agent transport.
- Reviewing kit code, agent defs, tool implementations, hook configs, prompts — to spot drift.
- Debugging an agent that's looping, leaking cache, busting context, fanning out unsafely.
- Comparing Claude Code CLI to Agent SDK / LangGraph / OpenAI Agents / MS Agent Framework / Google ADK.
- Sanity-checking a change: "would Claude Code do it this way? if not, why?"
Decision tree — which reference do I load?
Load only the reference you need (each is self-contained):
| Intent | Load |
|---|
| "Is my design aligned with proven bets?" | references/architectural-bets.md |
| "Cross-cutting patterns / connective tissue" | references/cross-cutting-patterns.md |
| "I'm starting a new design — what should I ask?" | references/design-checklist.md |
| "Review this kit/agent/tool code" | references/review-checklist.md |
| "Walk me through the agent loop in detail" | references/agent-loop-anatomy.md |
| "Prompt-cache stability concerns" | references/cache-stability-rules.md |
| "Tool pipeline / MCP / remote transport / skills+hooks specifics" | references/tool-and-extension-internals.md |
| "CLI pattern vs Agent SDK; cross-framework applicability" | references/architectural-bets.md → "Agent SDK vs CLI" + "Cross-system matrix" |
| "Full chapter-by-chapter digest" | references/full-study.md |
The 5 architectural bets (one-liner each)
- Generator loop > callbacks. One async generator (
query()); 10 terminal + 7 continuation states in a discriminated-union return type.
- File-based memory > databases. Markdown on disk + Sonnet side-query for relevance. Observable, version-controllable, zero infra.
- Self-describing tools > central orchestrator. Each tool carries its own schema/permissions/concurrency-safety. MCP tools become first-class via the same interface.
- Fork agents > fresh agents (for parallel work). Forked sub-agents share parent's prompt cache → ~90% input-token discount on book-claimed numbers; measure your own fleet.
- Hooks > plugins. External processes via exit codes + JSON. Crashes isolated. Protocol stable since 1971 (Unix process exit + stdin/stdout).
Closing meta-principle
Push complexity to the boundaries. Messy outside (5 keyboard protocols, 8 MCP transports, untrusted hooks). Typed/exhaustive inside (ParsedKey, recalled memories, Tool objects, permission decisions). Each boundary absorbs chaos and exports order.
Quick-fire heuristics (apply before opening a reference)
- LLM-driven loop: typed discriminated union for termination ("why did we stop?"). Not a sentinel/flag.
- Prompt-cache surface: system prompt is
[static..., BOUNDARY, dynamic...]. Runtime branches before the boundary cause 2^N hash explosion. Cache-busters MUST be named DANGEROUS_* with a _reason parameter.
- Sub-agent spawn: decide explicitly — fork (cache-shared) vs fresh (clean context). High-overlap parallel → fork. Different domain → fresh.
- Extension surface: prefer hooks (process isolation) over plugins. Snapshot-and-freeze hook config at startup; never re-read at runtime (TOCTOU).
- Cross-session storage: files-on-disk first; DB only when profiling demands. User must
vim/grep/rm it.
- Timeouts: layered, each protecting one specific failure. Don't reuse one signal across requests.
How to apply
- Match activation cue → reference via the decision tree.
- Load only that reference.
- Quote the bet/pattern by name. e.g., "Violates Bet 3 — orchestrator switches on
tool.name. Move isConcurrencySafe(input) to the tool."
- Acknowledge intentional mismatch. Some patterns are scale-justified only (forked Ink renderer, 8 MCP transports). Smaller projects can simplify — say so.
- Calibrate to runtime. If the user is on the Agent SDK (not CLI), fork-agents and CLI-internal patterns may not apply — see SDK-vs-CLI section in
architectural-bets.md.
Sources & verification
Stable sources (design principles — rarely change)
- Architecture principles and bets:
references/architectural-bets.md
- Chapter-by-chapter digest:
references/full-study.md
- Source site:
https://claude-code-from-source.com/
Volatile sources (live specs — verify freshness before citing)
- Externally verified (Anthropic docs / MCP spec): cache pricing (1.25x write 5min, 2x write 1hr, 0.1x read), 1-hour TTL, workspace cache isolation (Feb 2026), Skills frontmatter, MCP transport set + SSE deprecation (March 2025), Agent SDK surface.
- Book-claimed only (direction, not benchmarks): 250K compact-fail-loop calls/day, 10.2%
cache_creation savings, ~90% prefix overlap, 4.6B chars/week, 1,730-LOC query.ts. Quote with "Claude Code's reverse-engineered design indicates..." not as confirmed metrics.
Scope
Architectural review/design guidance only. Does NOT write code (use t1k:cook / t1k:plan), replace your measurement, or apply identically to non-Claude frameworks (see cross-system matrix in architectural-bets.md).
