Walkthrough: Design a Domain-Aware Claude-Powered Coding Agent Grounded in this Compendium

A coding agent in 2026 is no longer a thin wrapper around a chat API — it is a multi-component runtime that retrieves domain context, edits real files, executes code in sandboxes, persists memory across sessions, defers to humans on destructive actions, and learns from its own outcomes. The interesting question is no longer “can Claude write code?” — the SWE-bench numbers settled that. The interesting question is: how do you ground the agent in a specific domain corpus so it writes the right code for your problem, with your conventions, citing your references?

This walkthrough is the recipe for building one such agent on top of this Compendium. The Compendium itself — Sciences, Engineering, Math + Compute, Society, Arts + Energy, Walkthroughs — becomes the agent’s grounded knowledge source. Claude Code CLI plus the Claude Agent SDK plus a small custom MCP server provides the runtime. Subagents handle specialized tasks (code review, test writing, refactoring, documentation, deeper research). Skills bundle reusable domain contexts. Hooks gate destructive operations. The agents-learning-protocol closes the loop so the agent gets better at each task class over time.

The build target: a coding agent that any engineer on this machine can summon from any project directory, that knows Sciences/Engineering/Compute/Society at the same depth as the Compendium itself, that respects the read-only constraint on the corpus, and that costs ~$0.05-0.50 per typical task. Build CAPEX is engineering time (4-6 weeks for one engineer); OpEx is mostly model spend.

1. What we’re building

Concretely, the agent has four jobs:

Read from the Compendium for domain context. Before writing code, the agent queries the Compendium via hybrid full-text + semantic search and pulls 4-12 relevant notes into its context. It cites by [[wiki-link]] so downstream humans can verify.
Write and edit code in a target project. The agent operates on a specific repository (passed as cwd) using Claude Code’s built-in Read / Write / Edit / Bash / Glob / Grep tools. It never edits the Compendium itself — that remains a human-curated reference layer.
Run on Claude Code CLI + Claude Agent SDK + custom MCP. Interactive sessions use the CLI; long-running or service-mode workflows use the SDK with the same agent definition. A small custom MCP server exposes the Compendium as queryable tools so the same agent works in Claude Desktop, Cursor, and any other MCP-aware host.
Self-improve via the agents-learning-protocol. After every task, the agent appends a one-line activity log and (if non-obvious) saves a finding into the private vault at d:\Vault\AI Vault\Research\Topics\ tagged with outcome:accomplished|failed|partial. The next session queries that history first — adapting, not blindly applying.

The agent is not a replacement for the engineer — it is a domain-aware pair-programmer that already read the relevant 50 notes before the conversation started.

Reference systems that shipped this pattern in 2024-2026: GitHub Copilot Workspace (project-aware), Cursor Composer (codebase-grounded), Replit Agent (deploy-aware), Cognition Devin (autonomous SWE), Anthropic Claude Code (CLI + skills + hooks + MCP), Sourcegraph Cody (enterprise code search + LLM). What’s missing from all of them is a shared, durable, human-curated domain corpus that is neither the source code nor a vector DB of arbitrary URLs — that is what the Compendium provides here.

2. Specification

Parameter	Target	Notes
Supported languages	Python, JS / TS, Java, C++, Rust, Go (plus shell, SQL, HCL)	Inherits Claude’s full polyglot range
Domain depth	Sciences, Engineering, Math + Compute, Society, Arts + Energy + 46 Walkthroughs	Compendium-grounded via MCP search
Iteration cycle	<5 min for a typical edit-test-review loop	p95 budget
Cold-start latency	<10 s from invocation to first tool call	CLI launch + cache warm
Tool-call latency	<2 s per tool round-trip	Local MCP + cached Compendium queries
Code-review pass	<30 s for a 200-LOC diff	Sonnet 4.6 inline
Cost per task	$0.05-0.50 (cached); $0.50-2.00 (uncached / Opus)	Model-cascade Section 4
Compendium constraint	Read-only — agent must never write to `d:\Vault\Compendium\`	Enforced via PreToolUse hook
Target-project constraint	Edits only inside the cwd at invocation	Boundary-enforced
Memory horizon	Cross-session via `obsidian-research.mjs` save / query	Adapts from outcome-tagged history
Availability	Best-effort (single-user / small-team CLI)	Not a 99.9% SLO product
Observability	Per-session logs to `~/.claude/projects/<id>/logs/` + optional Langfuse / Phoenix	OTel GenAI conventions

These targets are deliberately modest compared to the multi-tenant agent platform of design-agent-platform-deployment. This is a per-engineer / per-team agent, not a hosted product — single-user concurrency, local execution, durable cross-session memory via Obsidian rather than a managed checkpointer.

3. Architecture overview

                     +---------------------+
                     |   Engineer          |
                     |   (terminal / IDE)  |
                     +----------+----------+
                                |
                       claude code / claude-agent-sdk
                                |
                                v
        +------------------------------------------------+
        |     Primary coding agent  (Sonnet 4.6)         |
        |  - reads system prompt + Compendium pointers   |
        |  - cascades down to Haiku, up to Opus          |
        |  - routes work to subagents                    |
        +---+----------+-------------+--------+----------+
            |          |             |        |
            v          v             v        v
     +-----------+ +----------+ +--------+ +----------------+
     | Compendium| | Target   | | Subagents| | Memory tool +|
     | MCP server| | project  | | (.claude/| | obsidian-    |
     | (custom)  | | (cwd)    | | agents/) | | research.mjs |
     |  - search | |  - Read  | | review,  | |  save / log  |
     |  - read   | |  - Edit  | | test,    | |  query       |
     |  - list   | |  - Bash  | | refactor,| |              |
     |           | |  - Glob  | | docs,    | |              |
     |           | |  - Grep  | | research | |              |
     +-----------+ +----------+ +--------+ +----------------+
            |                                       |
            v                                       v
     +-------------+                       +----------------+
     | d:\Vault\   |                       | d:\Vault\AI    |
     | Compendium  | <-- READ-ONLY         | Vault\         |
     |             |                       | Research\      |
     |             |                       | Sessions, etc. |
     +-------------+                       +----------------+

Components:

The primary agent is a Claude Code session (or Claude Agent SDK process) configured with a domain-aware system prompt and the agent-set + skill-set + MCP-set defined below.
The Compendium MCP server exposes the corpus as three read-only tools so any MCP-aware client (Claude Desktop, Cursor, VS Code Continue, future Claude API agents) can use the same knowledge layer.
Subagents in .claude/agents/ are specialized prompts that the primary agent dispatches via the native Task tool — each runs in an isolated context window.
The memory layer is the existing Obsidian-backed research layer documented in this machine’s CLAUDE.md — no parallel store, no AgentDB, no RVF.

Every piece below cross-references the canonical Claude sub-library notes — _index is the single MOC for the whole stack.

4. Component selection

4.1 Runtime — CLI vs SDK

Two valid runtime paths; pick by interaction mode, not by capability:

Runtime	Use when	Sources
Claude Code CLI v1.x (latest stable; quarterly releases through 2025-2026)	Interactive sessions — terminal, IDE plugin, single-engineer workflow	claude-code-cli
Claude Agent SDK (Python 0.3+ / TypeScript 0.5+, GA 2025)	Service mode — CI agent, scheduled job, batch refactor, multi-agent backend	claude-agent-sdk

The SDK and CLI share the same primitives (subagents, skills, hooks, MCP, model cascade), so a single agent definition in .claude/agents/ works in both. Build for the CLI first; promote to SDK when a workflow needs to run unattended. Reference: claude-api-and-sdks.

4.2 Model cascade

Three-tier cascade for cost + latency control. Set the default via model in agent frontmatter; override per subagent via CLAUDE_CODE_SUBAGENT_MODEL env var or per-call options.

Tier	Model	When	Approx cost (cached / uncached)
Fast / router / classifier	Claude Haiku 4.5	quick routing decisions, classification, planning, simple file ops	$0.0008 / $0.008 per 1K tokens (illustrative)
Workhorse	Claude Sonnet 4.6	most code reading, writing, review, refactoring	$0.003 / $0.03 per 1K tokens
Hard problems	Claude Opus 4.7	architecture decisions, deep debugging, multi-file refactors with cross-cutting reasoning	$0.015 / $0.075 per 1K tokens

Routing strategy: Sonnet 4.6 is the default. Subagents that do bounded, well-defined work (test-writer, docs-writer, single-file refactor) are pinned to Haiku 4.5 via CLAUDE_CODE_SUBAGENT_MODEL=haiku. Opus 4.7 is invoked explicitly when the primary agent recognizes a hard problem (/think hard or escalation in the prompt). Reference: claude-models-and-capabilities.

4.3 Prompt caching — the single biggest cost lever

Anthropic prompt caching, especially with the extended-cache-ttl-2025-04-11 beta header and ttl: "1h" cache control, cuts cost of repeated calls by 80-90% on agent workloads where the system prompt + tools + Compendium context blocks are stable across many turns.

Cache breakpoint placement (in order from system → user):

System prompt (role + capabilities + safety rules) — cache, TTL 1h
Compendium summary block (the _index pointers + the 8-12 most relevant notes for this session) — cache, TTL 1h
Tool definitions + MCP tool schemas — cache, TTL 1h
Conversation history — uncached (mutates each turn)
Current user turn — uncached

Expected hit rate on a sustained session: 85-95% on the first three blocks. Reference: prompt-caching.

4.4 Tool stack

The agent uses three tool layers:

Built-in Claude Code tools — Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task (for subagent dispatch). These are always available in CLI / SDK sessions. Reference: tool-use-and-function-calling.
Custom MCP server for Compendium (Section 4.7 below) — exposes the corpus as queryable tools.
Memory tool + obsidian-research.mjs CLI — used by the agent for cross-session save / log / query. Native memory tool (beta 2025) is also wired but the durable layer is Obsidian.

Reference: mcp-protocol.

4.5 Subagent architecture

Five specialized subagents live in .claude/agents/ (project-scoped) or ~/.claude/agents/ (user-scoped, available everywhere):

Subagent	Model pin	Scope	What it does
`code-reviewer`	Sonnet 4.6	per-PR / per-diff	Reviews a diff for correctness, style, security, test coverage. Cites Compendium notes for any architectural concern.
`test-writer`	Haiku 4.5	per-function / per-file	Writes unit + integration tests in the project’s existing framework (pytest, vitest, junit, cargo test, go test).
`refactor`	Sonnet 4.6	scoped to a file or module	Performs a named refactor (extract method, rename, restructure) preserving behavior; runs tests after.
`docs-writer`	Haiku 4.5	per-module	Writes / updates README / API docs / inline docstrings.
`compendium-researcher`	Sonnet 4.6	per-question	Goes deep on a topic — runs hybrid search, fetches 5-10 notes, synthesizes findings, optionally proposes a new vault Topic note for human review.

The primary agent dispatches via Task(subagent_type="code-reviewer", ...) and each subagent runs in its own context window — no shared state except via files. Reference: claude-code-subagents-and-skills and agents-and-orchestration-patterns.

4.6 Skills — bundled domain contexts

Skills (Claude Code 2025 feature) bundle a system-prompt fragment + supporting files into a reusable unit. They are the right abstraction for “here is the domain context for working in this stack”. Ship at least these:

Skill	Bundles	When invoked
`compendium-context`	Top-level `_index.md` files + selection-tree pointers	Every session — auto-invoked
`fintech-stack`	Society/Finance notes + relevant Compute notes (auth, compliance, payments)	When working on a fintech project
`bio-stack`	Sciences/Biology + Sciences/Chemistry + relevant Compute notes (data eng, RAG)	When working on bio / lab software
`realtime-stack`	Engineering/realtime-embedded + Compute/concurrency-primitives + relevant Math	When working on robotics / control / streaming
`web-stack`	Compute/web-frameworks + frontend notes + design-saas-platform-launch	When working on a web app

The agent auto-selects a skill based on the cwd’s package.json / Cargo.toml / pyproject.toml / Compendium-relevant signals via the UserPromptSubmit hook (Section 4.8). Reference: claude-code-subagents-and-skills.

4.7 MCP server for Compendium

A small Node.js MCP server exposes the Compendium as read-only tools. The server wraps the existing obsidian-research.mjs CLI (already on this machine), so it inherits the hybrid search + filesystem walk for free.

Reference implementation: scripts/mcp-server/ — TypeScript on the official @modelcontextprotocol/sdk over stdio transport. Five tools: search_compendium, read_note, list_walkthroughs, list_libraries, get_note_graph. Install via npm install && npm run build inside the directory, then register the resulting dist/index.js in ~/.claude/settings.json under mcpServers.compendium. See the README in that directory for full setup and per-tool invocation examples.

The sketch below shows the minimum-viable shape; the reference implementation extends it with path-safety checks, frontmatter parsing, graph traversal, and a category-grouped walkthrough catalog.

// server.ts (sketch — full implementation at scripts/mcp-server/src/)
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { execSync } from "node:child_process";
import { readFileSync } from "node:fs";
 
const server = new Server({ name: "compendium", version: "1.0.0" }, { capabilities: { tools: {} } });
 
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "search_compendium",
      description: "Hybrid search across the Compendium (full-text + semantic).",
      inputSchema: { type: "object", properties: {
        query: { type: "string" },
        k: { type: "number", default: 8 }
      }, required: ["query"] }
    },
    {
      name: "read_note",
      description: "Read a Compendium note by relative path.",
      inputSchema: { type: "object", properties: {
        path: { type: "string", description: "Path relative to d:/Vault/Compendium" }
      }, required: ["path"] }
    },
    {
      name: "list_walkthroughs",
      description: "Return the catalog of walkthroughs.",
      inputSchema: { type: "object", properties: {} }
    }
  ]
}));
 
server.setRequestHandler("tools/call", async (req) => {
  if (req.params.name === "search_compendium") {
    const { query, k = 8 } = req.params.arguments;
    const out = execSync(
      `node ${process.env.HOME}/.claude/bin/obsidian-research.mjs query ` +
      `${JSON.stringify(query)} --hybrid --k ${k} --compendium-only --json`
    );
    return { content: [{ type: "text", text: out.toString() }] };
  }
  if (req.params.name === "read_note") {
    const txt = readFileSync(`d:/Vault/Compendium/${req.params.arguments.path}`, "utf8");
    return { content: [{ type: "text", text: txt }] };
  }
  if (req.params.name === "list_walkthroughs") {
    const idx = readFileSync("d:/Vault/Compendium/Walkthroughs/_index.md", "utf8");
    return { content: [{ type: "text", text: idx }] };
  }
});

Register it in ~/.claude/settings.json under mcpServers with full auto-approval (read-only is safe). Reference: mcp-protocol.

4.8 Hooks — gating, routing, logging

Three hook types do meaningful work:

Hook	Trigger	Purpose
`UserPromptSubmit`	Every user turn	Detect cwd signals (`Cargo.toml`, `pyproject.toml`, presence of `marketing-site/`) and auto-invoke the matching skill
`PreToolUse` on `Bash`	Before any shell command	Regex-match destructive patterns (`rm -rf`, `git push --force`, `DROP TABLE`, `kubectl delete`) and block + ask user
`PreToolUse` on `Write` / `Edit`	Before any file edit	Reject edits whose path is inside `d:\Vault\Compendium\` — read-only constraint
`PostToolUse` on `Task`	After a subagent finishes	Append a one-line entry to today’s session log via `obsidian-research.mjs log`

Reference: claude-code-hooks-deep.

5. Sizing math

Typical request flow for a single coding task (“add a retry-with-backoff wrapper to this HTTP client”):

Stage	Tokens in	Tokens out	Cached?
System prompt + safety rules	1,500	—	yes (1h TTL)
Compendium context block (4 relevant notes)	4,000	—	yes (1h TTL)
Tool + MCP schemas	1,500	—	yes (1h TTL)
Conversation history	500-3,000	—	no
Current user turn	200	—	no
Model reasoning + tool dispatch (5-10 calls)	per-call 50-200 in / 50-300 out	—	partial
Final synthesis	—	500-2,000	no

Token totals per task: 10K in (mostly cached) + 2-5K out + 5-10 tool calls × 200 tokens each. With Sonnet 4.6 and 90% cache-hit rate, the per-task cost lands at $0.05-0.20 for typical work. Opus 4.7 hard tasks land at $0.30-1.50. Daily budget for one heavy user (50 tasks): **$5-15**. For a team of 10 engineers: **$50-150/day**, or **$1.5-4.5K/month**.

These numbers assume aggressive caching and a Sonnet-default cascade — without caching, costs multiply by 5-10×. Reference: prompt-caching for the math derivation.

6. System prompt template

The system prompt structure is XML-tagged for Claude’s preferred input format (per Anthropic’s published prompt-engineering guidance). Here is the canonical shape — instantiate at agent definition time, cache the rendered string for 1h.

<role>
You are a domain-aware coding agent. You have read the Compendium at d:\Vault\Compendium\
and you cite it by wikilink when relevant. Your job is to read the user's target project
(cwd at session start), understand what they want, retrieve relevant Compendium context,
write code, run tests, and verify the result.
</role>
 
<context>
The Compendium covers: Sciences (Biology, Chemistry, Physics, Earth, Astronomy),
Engineering + Robotics, Math + Compute (including the Claude sub-library), Society
(Finance, Law, Economics, History, Linguistics), Arts + Energy + ClimateScience,
plus 46 end-to-end Walkthroughs that exercise the libraries together.
 
Master MOC entry points:
- Compute sub-library: [[Math-and-Compute/Compute/_index]]
- Claude-specific: [[Math-and-Compute/Compute/Claude/_index]]
- Walkthroughs: [[Walkthroughs/_index]]
 
When you need domain context, call the `search_compendium` MCP tool first. Build on
existing notes rather than re-researching from scratch.
</context>
 
<capabilities>
You have Read / Write / Edit / Bash / Glob / Grep / WebFetch / WebSearch / Task.
You have MCP tools `search_compendium`, `read_note`, `list_walkthroughs`.
You can dispatch to subagents: code-reviewer, test-writer, refactor, docs-writer,
compendium-researcher. Use Task for any work that fits a subagent's scope.
</capabilities>
 
<read-only-rule>
The Compendium at d:\Vault\Compendium\ is read-only for you. You may query it,
read it, and cite it, but you must NEVER write to it. If you discover a finding
that belongs in the Compendium, propose it via a handoff note in the user's
private vault at d:\Vault\AI Vault\Research\Topics\ and mention it to the user.
The Compendium is human-curated; you are a consumer not a contributor.
</read-only-rule>
 
<style>
Match the style of the target project. Read package.json / pyproject.toml / Cargo.toml
to detect framework + linting conventions. Cite Compendium notes by [[wikilink]] in
comments when the choice is non-obvious. Prefer editing existing files to creating
new ones. No emojis.
</style>
 
<safety>
Destructive shell operations (rm -rf, git push --force, DROP TABLE, kubectl delete)
are blocked by PreToolUse hook unless explicitly approved. Tool retry on transient
errors only — never retry destructive ops. Stop and ask before any payment, email
send, account modification, or production deployment.
</safety>

Reference: prompt-engineering-for-claude for the XML-tagging convention and Claude-specific prompt patterns.

7. Controls + safety

Defense in depth across four layers:

Layer	Mechanism	Reference
Permission mode	Default `read` for Compendium MCP; `acceptEdits` for target project; `bypassPermissions` OFF	claude-code-cli
PreToolUse hooks	Block destructive Bash patterns; reject any Write / Edit whose path is inside the Compendium	claude-code-hooks-deep
Sandboxing	Agent runs as the user, not as admin; can’t touch other projects without explicit cross-project handoff	inherits machine’s CLAUDE.md rules
Confirmation gates	Destructive actions require explicit user approval — surfaced as `confirm_required: true` on tool schema	agents-and-orchestration-patterns

The single most important rule, repeated from the system prompt and enforced at the hook layer: the Compendium is read-only. An agent that silently edits its own knowledge source is uncontainable — it can corrupt the corpus, hide its tracks, and feed itself bad context next turn. The PreToolUse hook on Write / Edit rejects any path beginning with d:\Vault\Compendium\ with a clear error message routing the agent to the private vault Research/Topics path for proposed contributions.

Other guardrails worth shipping from day one:

Per-session token cap — hard limit of 500K tokens per session to bound runaway loops. Set via CLAUDE_CODE_MAX_TOKENS_PER_SESSION (illustrative env var).
Tool-call cap — hard limit of 50 tool calls per turn. The model is encouraged to think, plan, and act in batches.
Subagent depth limit — subagents cannot dispatch other subagents (max depth 1). Prevents fan-out blowups.
Web access — WebFetch / WebSearch allowed but logged; results pass through the existing auto-capture hook that saves any non-obvious finding into the vault’s Sources folder.

Reference: hidden-tricks-and-gotchas covers a number of less-obvious failure modes (silent context truncation, hook ordering, MCP tool naming collisions).

8. Observability

Three observability layers, each optional but cumulatively powerful:

Layer	What	Where it lives
Built-in session logs	Every tool call, prompt, response	`~/.claude/projects/<project-id>/logs/<session-id>.jsonl`
Structured tracing	OpenTelemetry GenAI spans for every LLM call + tool invocation	OTel collector → Langfuse / Phoenix / LangSmith / Sentry GenAI
Cost tracking	Per-session token + dollar attribution	Anthropic billing API + per-session tag

For a single-engineer setup, the built-in logs at ~/.claude/projects/<project>/logs/ are sufficient — they’re already JSONL and grep-able. For team or production use, enable OTel export via CLAUDE_CODE_OTEL_ENDPOINT (illustrative env var) and point at a self-hosted Langfuse or Phoenix. The OTel GenAI semantic conventions (stable 2024-2025) define spans for gen_ai.client.operation, gen_ai.tool.invocation, gen_ai.usage.input_tokens, etc. — same substrate as the multi-tenant platform of design-agent-platform-deployment.

Per-trace must capture: session-id, project-id, user prompt hash, model, prompt tokens, completion tokens, cached tokens, cost in cents, tool calls + their args (redacted as needed) + results + latency, error class. This is the substrate for cost dashboards and the self-improvement loop in Section 9.

Reference: claude-code-cli for built-in logging behavior and the _index observability sub-section.

9. Self-improvement loop

Closing the loop is what separates an agent from a chatbot. The protocol — documented in agents-learning-protocol and reinforced in this machine’s user-level CLAUDE.md — is:

Query before researching. Before any non-trivial decision, run obsidian-research.mjs query --hybrid --k 8 "<question>". The hybrid mode combines full-text (exact-token) + semantic (embedding) recall via reciprocal-rank fusion. Build on prior findings rather than starting from scratch.
Adapt, don’t blindly apply. Saved notes are time-stamped claims, not ground truth. Verify against current code / sources before acting. Update or supersede notes that turn out to be wrong.
Save non-obvious findings. After each task, if the agent discovered something that took real work and is likely useful to a future session, save it via obsidian-research.mjs save --title ... --tags topic,domain --agent claude-code-coding-agent --body .... Tag with outcome:accomplished | outcome:failed | outcome:partial so future queries can filter by what worked.
Log at breakpoints. Append a one-line obsidian-research.mjs log "what I just figured out / decided" at natural decision points. This makes today’s session readable by tomorrow’s session in seconds.
Re-index after a batch. Semantic search relies on a local embedding index. After saving multiple notes, run obsidian-research.mjs index (incremental — only re-embeds changed notes).

Crucially: the Compendium itself is never updated by the agent. Proposed contributions go into d:\Vault\AI Vault\Research\Topics\ and the human curator (per the read-only rule) decides whether to promote into the Compendium during routine vault hygiene. This keeps the corpus high-signal and prevents the feedback-loop pathology where an agent trains on its own (possibly wrong) prior output.

Reference: agents-learning-protocol for the canonical protocol; Conventions for the vault’s overall write conventions; AGENTS.md for the operating manual every agent reads on startup.

10. Cost build-up

Per-engineer-per-day, assuming ~50 tasks/day with 10% routed to Opus and 90% to Sonnet, 90% cache-hit rate on the system + Compendium + tool blocks:

Item	Per session	Daily (50 sessions)	Monthly (~22 working days)
Sonnet 4.6 cached reads	$0.02	$1.00	$22
Sonnet 4.6 fresh writes	$0.10	$5.00	$110
Opus 4.7 for hard tasks (10%)	$0.50	$2.50	$55
Haiku 4.5 subagent ops	$0.005	$0.25	$5.50
MCP server hosting (local Node process)	$0	$0	$0
Obsidian REST API + research CLI (local)	$0	$0	$0
Per-engineer total	~$0.15	~$8.75	~$200

Scaled to a team of 10 engineers: ~$2,000/month. Scaled to 50 engineers: ~$10,000/month. At enterprise contract scale (1000+ active engineers across an org), Anthropic enterprise contracts cut these by 30-50% via volume commits and dedicated capacity. For comparison, the multi-tenant agent platform of design-agent-platform-deployment runs $1.5-6M / year in LLM spend serving 1000-5000 concurrent sessions — three orders of magnitude more, because that platform is renting capacity to many tenants, not just one team.

Hidden costs to budget for:

Initial caching warm-up — first session of the day pays full price on the 7K-token cache block; subsequent sessions inside the 1h TTL window are 90% cheaper. Run a tiny scheduled session every 50 minutes during working hours to keep the cache warm if cost matters more than wall-clock.
Failed-loop costs — an agent stuck in a retry loop can burn $5-20 in a few minutes. The tool-call cap (Section 7) bounds this.
WebFetch + WebSearch — these are not free in production builds; budget ~10% on top for web access.

11. Schedule

A realistic single-engineer build schedule:

Week	Work	Outputs
1	MCP server for Compendium	Working `search_compendium` / `read_note` / `list_walkthroughs` tools registered in `~/.claude/settings.json`; smoke-tested from Claude Code
2	Agent + subagent definitions, skill bundles	`.claude/agents/*.md` for the 5 subagents; `~/.claude/skills/compendium-context/SKILL.md` + stack-specific skills; routing logic via UserPromptSubmit hook
3	Hook integration + permission tuning	PreToolUse hooks for Bash blocklist + Compendium read-only; PostToolUse logging hook; settings.json reviewed
4	Cost + latency benchmarking + iteration	A 20-task golden eval set; per-task cost + latency measured cached / uncached / Opus; cache-hit-rate target ≥85% verified
5+	Continuous improvement	Self-learning loop running; weekly review of `outcome:failed` tagged notes to find patterns; subagent prompt tuning

Critical milestones:

End of Week 1 — agent can answer “what does the Compendium say about X” via MCP without manually cat-ing files. This is the smallest demonstrable wedge.
End of Week 2 — agent can complete an end-to-end task (“add feature Y to project Z”) that touches code + tests + docs, using subagents and citing 2-3 Compendium notes.
End of Week 4 — cost-per-task lands inside the $0.05-0.50 target band on the golden eval set. If not, the cache placement or model cascade needs another pass.

After Week 5, the system is in maintenance mode. New domain coverage comes from adding Compendium notes (which the agent picks up automatically via the MCP). New code conventions come from updated skills. The agent’s prompts themselves rarely need editing after Week 4 — that is the design goal.

12. Cross-references summary

The full Compendium notes that inform this design:

Claude sub-library (the canonical reference for everything Claude-specific):

_index — sub-library MOC
claude-models-and-capabilities — Haiku / Sonnet / Opus tiers + selection criteria
claude-api-and-sdks — Anthropic API + Python / TS SDKs
prompt-caching — cache breakpoints + TTL + cost math
tool-use-and-function-calling — native + MCP tool patterns
claude-code-cli — CLI runtime + permissions + logging
claude-code-hooks-deep — hook types + ordering + recipes
claude-code-subagents-and-skills — subagent + skill model
mcp-protocol — MCP spec + client + server patterns
claude-agent-sdk — SDK for service / background use
prompt-engineering-for-claude — XML tags + system-prompt patterns
agents-and-orchestration-patterns — multi-agent orchestration patterns
hidden-tricks-and-gotchas — non-obvious failure modes

Compute synthesis layer:

_compare_consistency_models — relevant when the agent reasons about distributed state
_compare_service-architectures — when picking a deployment model for the agent itself
_learn_next — next-step learning paths for the engineer building this

System:

agents-learning-protocol — the canonical contract every agent on this machine follows
Conventions — vault write conventions, frontmatter, tagging
AGENTS.md — operating manual every agent reads on session start

13. Adjacent

design-agent-platform-deployment — the multi-tenant production analog (1000+ concurrent sessions, billing, isolation)
design-rag-at-scale-system — the retrieval layer pattern when the corpus grows beyond Obsidian scale
design-realtime-inference-fleet — the inference substrate underneath if you self-host the model
design-llm-training-cluster — where Claude’s weights come from
design-saas-platform-launch — the multi-tenant SaaS surrounding a hosted version of this agent
_index — the canonical Claude sub-library MOC
prompt-engineering-agent-systems — generic (vendor-agnostic) agent + prompt patterns
observability-stack — OTel GenAI conventions for tracing the agent in production
agents-learning-protocol — the cross-session memory + adaptation protocol
Conventions — vault and corpus write conventions

Compendium

Explorer

Walkthrough: Design a Domain-Aware Claude-Powered Coding Agent Grounded in this Compendium

Walkthrough: Design a Domain-Aware Claude-Powered Coding Agent Grounded in this Compendium

1. What we’re building

2. Specification

3. Architecture overview

4. Component selection

4.1 Runtime — CLI vs SDK

4.2 Model cascade

4.3 Prompt caching — the single biggest cost lever

4.4 Tool stack

4.5 Subagent architecture

4.6 Skills — bundled domain contexts

4.7 MCP server for Compendium

4.8 Hooks — gating, routing, logging

5. Sizing math

6. System prompt template

7. Controls + safety

8. Observability

9. Self-improvement loop

10. Cost build-up

11. Schedule

12. Cross-references summary

13. Adjacent

Graph View

Table of Contents

Backlinks