| name | claude-code-methodology |
| description | Production-grade Agent development methodology derived from Claude Code. 11-dimension framework covering tool design, system prompts, permissions, multi-agent orchestration, token economy, memory, extensibility, conversation loop, workflow modes, task lifecycle, and observability. Supports architecture design, implementation guidance, and agent review. Trigger on "Agent design", "build an agent", "AI agent", "tool design", "system prompt architecture", "agent review", "multi-agent", "compaction", "agent workflow modes", "background tasks", "agent observability", or any agent development concern. |
Agent Development Methodology
Production-grade patterns from a real coding agent
All patterns in this skill are derived from a production coding agent at scale. They are not theoretical — every pattern shown is validated by use against real engineering problems by real engineers. The patterns are framework-agnostic; the dimensions, the trade-offs, and the discipline transfer to any technology stack.
Detect Mode and Jump In
Identify which mode the user needs, then work through it directly:
| Mode | User context | Action |
|---|
| Architecture | "I want to build an agent that..." / designing from scratch | Gather requirements → work through relevant dimensions → produce architecture design |
| Implementation | "How do I design X?" / "What's the best approach for Y?" | Identify dimension → load reference file → apply pattern to their context |
| Review | Sharing existing code or design for critique | Read their work → evaluate each relevant dimension → structured review output |
The 11 Dimensions
A production agent should be evaluated along these dimensions. Not all apply equally for every project — but every production design touches at least seven, and ignoring any one of them creates a class of failures that the dimension would have prevented.
| # | Dimension | Core question | Reference |
|---|
| 1 | Tool Design | Are tools safe, well-described, composable, and self-declarative? | references/01-tool-design.md |
| 2 | System Prompt Architecture | Is the prompt modular, layered, and cache-disciplined? | references/02-system-prompt.md |
| 3 | Permission and Safety | Is the agent fail-closed, with structured decisions and an operator ceiling? | references/03-permission-safety.md |
| 4 | Multi-Agent Orchestration | Is the right topology used per task (fork/fresh/worker/team/remote/scheduled)? | references/04-multi-agent.md |
| 5 | Context and Token Economy | Are the four token pools managed with the right strategies (cache, defer, compact, evict)? | references/05-token-economy.md |
| 6 | Memory and State | Are the five state categories distinguished, and is persistent memory file-based and triggered? | references/06-memory-state.md |
| 7 | Extensibility | Can hooks, skills, MCP, and plugins extend the agent without modifying it? | references/07-extensibility.md |
| 8 | Conversation Loop | Is the loop streaming, interruptible, retry-aware, and invariant-preserving? | references/08-conversation-loop.md |
| 9 | Workflow Modes | Are there structural mode primitives (plan, worktree) for phase-level constraints? | references/09-workflow-modes.md |
| 10 | Task Lifecycle | Are background tasks first-class objects with status, output, cancellation, resume? | references/10-task-lifecycle.md |
| 11 | Observability and Cost | Is every interesting moment structured, attributed, and queryable? | references/11-observability.md |
Mode 1: Architecture Design
When designing a new agent, work through this sequence:
Step 1 — Understand the agent's purpose and boundaries
Gather (ask or infer):
- What actions can the agent take? (→ determines tool inventory and safety profiles)
- What can go wrong? What's the blast radius of a mistake? (→ determines permission model and modes)
- Who are the users and how much should the agent trust them? (→ determines default permission mode, audience variants)
- Does it need memory across sessions? (→ determines memory architecture)
- Will it delegate work to sub-agents? (→ determines multi-agent topology)
- What's the expected conversation length? (→ determines compaction strategy)
- Will it run autonomously or only interactively? (→ determines observability rigor, budget enforcement)
- Will it need to be extensible by third parties? (→ determines hook/skill/plugin design)
Step 2 — Identify which dimensions are critical
| Agent type | Always critical | Often critical | Sometimes critical |
|---|
| Simple task agent | 1, 2, 3 | 5 | 6, 8 |
| Long-running coding agent | 1, 2, 3, 5, 6, 8, 9 | 4, 10, 11 | 7 |
| Multi-agent / coordinator | 1, 2, 3, 4, 8, 10 | 5, 6, 9, 11 | 7 |
| Autonomous / scheduled | 1, 2, 3, 10, 11 | 4, 5, 6, 8 | 7, 9 |
| Plugin-extensible production | All 11 | — | — |
Step 3 — Load relevant reference files and apply patterns
Read the relevant references/ files for the critical dimensions and translate the patterns to the user's stack and constraints. Each reference has a Design Checklist at the end — use it to verify your design.
Step 4 — Produce an architecture design document
Structure the output as:
## Agent Architecture: [name]
### Tool Inventory
[list tools with safety profiles: read-only / write / destructive; per-input safety functions]
### System Prompt Structure
[static sections inventory; dynamic sections inventory; boundary marker; audience variants]
### Permission Model
[default mode; mode ladder; rule sources; bypass-immune ceiling; classifier policy]
### Memory and State
[session state shape; persistent memory directory layout; the four memory types in use]
### Multi-Agent Topology (if applicable)
[fork/fresh/worker/team/remote choices per task; worktree usage; coordinator workflow]
### Token Economy
[effective window calc; compaction strategy stack; cache strategy; tool result budget]
### Conversation Loop
[streaming approach; cancellation; retry policy; compact_boundary handling]
### Workflow Modes
[plan mode and exit deliverable; worktree mode if applicable; other modes if invented]
### Task Lifecycle
[background task types in use; concurrency limits; resume policy]
### Extensibility
[hook events surfaced; skill loading; MCP server inventory; plugin packaging if applicable]
### Observability
[per-turn metrics; cost attribution dimensions; budget enforcement; session summary]
Mode 2: Implementation Guidance
When the user has a specific implementation question:
-
Map to a dimension. "How do I truncate tool results?" → Dimension 5. "How does fork share a cache?" → Dimension 4. "How do I structure my permission decisions?" → Dimension 3.
-
Read the relevant reference file for the dimension.
-
Apply the pattern to their context. Adapt the canonical pattern to their stack (Python/LangChain/CrewAI/custom) and constraints. Show them what the analogue looks like in their world.
-
Explain WHY, not just what. Each pattern has a problem it solves — explain the problem and how the pattern addresses it. Patterns without their reasoning don't transfer; patterns with their reasoning do.
Mode 3: Agent Review
When the user shares existing agent code or a design for review:
-
Read their code/design. Understand what's there before evaluating.
-
Evaluate relevant dimensions. Not every review needs all 11; focus on what matters for their agent type and stated concerns.
-
Prioritize findings:
- 🔴 Critical — safety/correctness issues that could cause real harm, data loss, security problems, or runaway cost
- 🟡 High — architectural issues that will compound over time (monolithic prompt, no context management, no observability)
- 🟢 Low — optimization opportunities (cache not used, defer not used, cost attribution missing)
-
Output structured review:
## Agent Review
### 🔴 Critical Issues
- [issues that could cause harm, data loss, security problems, or runaway cost]
### 🟡 Architectural Concerns
- [issues with structure that will compound over time]
### 🟢 Optimization Opportunities
- [efficiency, cost, latency improvements]
### ✅ What's Well-Designed
- [acknowledge genuinely good patterns — be specific]
### Recommended Changes (Priority Order)
1. [most impactful change]
2. ...
Core Principles (from the design philosophy)
These are the highest-level invariants extracted across all 11 dimensions. Apply them as sanity checks on any agent design.
-
Fail-closed over fail-open. When permission is ambiguous, deny by default. When the classifier errors, deny. When the input is malformed, ask. Safety must be explicitly granted, not assumed.
-
Token economics drive architecture. Every structural decision — section boundaries, tool loading, result storage, fork strategy — should consider token cost. Bad economics matter at 100K users.
-
Static and dynamic must be separated. Stable instructions go in cacheable sections; volatile data goes in dynamic sections. Mixing them wastes cache and degrades silently.
-
Tools define capability boundaries. The tool set IS the agent's capability model. What isn't a tool can't be done. This makes abilities explicit and auditable.
-
Extensibility through protocols and events, not inheritance. Hooks (shell commands), Skills (markdown), MCP (RPC), Plugins (bundles) — never subclass.
-
Recursive delegation is a design primitive. Agents spawn agents; design every tool interface as if a sub-agent might also call it.
-
The permission model is a spectrum, not a switch. Default → plan → acceptEdits → bypassPermissions → auto is a dial users adjust based on trust and task; the ceiling is operator-controlled.
-
Modes are structural constraints with deliverables. Plan mode and worktree mode are first-class state transitions the model enters via tools, with concrete completion artifacts.
-
Background work is a first-class primitive. Tasks are persistent state, not transient processes. They survive restarts, deliver results asynchronously, and have observable lifecycles.
-
Every interesting moment is structured. Permission decisions, cost transitions, hook executions, compactions — all carry structured reasons. Logs are queryable; analytics are answerable.
-
The agent should know its own state. Cost trajectory, budget headroom, token pressure, recent failures — surface this in the model's context so the model can make cost-aware and pressure-aware choices.
Worked Example: A "PR Review Agent" Across All 11 Dimensions
A reviewer agent that takes a PR URL and produces a structured review with priorities, security checks, and verification suggestions. We walk through how each dimension shapes the design.
1. Tool Design. The reviewer needs gh_pr_view (for PR metadata), file_read (for diffed files), grep (for finding callers), web_search (for security CVEs), and submit_review (the final action). Each tool declares per-input safety: gh_pr_view is read-only regardless of input; submit_review is destructive (publishes). The submit tool's prompt explicitly says WHEN NOT TO USE — "do not submit until you have a complete review with priorities and at least one verification recommendation per change category."
2. System Prompt. The static section defines the reviewer's persona ("you find bugs that would ship to production"), the review structure (intro / per-file / synthesis), and the boundary between observed and inferred. The dynamic section carries the PR's metadata (URL, author, base branch, current date) and the user's review depth preference (cursory / standard / paranoid).
3. Permission and Safety. The reviewer runs in plan mode by default — it reads but cannot mutate the repo. The submit_review tool is the only write and requires user confirmation regardless of mode. The classifier policy is "the reviewer should never auto-approve writes; it should always ask."
4. Multi-Agent. For large PRs (>20 files), the main reviewer spawns fork sub-agents to review file groups in parallel — they share the parent's prompt cache (cheap), produce structured per-file reports, and the main reviewer synthesizes. For security review specifically, it spawns a fresh subagent with a hardened security prompt (not biased by the main reviewer's "looks fine" conclusions).
5. Token Economy. The PR diff itself can be large; results are subject to per-tool truncation. The conversation-level result budget evicts oldest file contents after synthesis is complete — the reviewer only needs the recent files for follow-up Q&A. Forks share prompt cache; the cache is the difference between affordable and not at scale.
6. Memory and State. The reviewer extracts feedback memories: "this team prefers integration tests over unit tests for service layer", "team blocks PRs without RFC for any DB schema change". On the next review, these are auto-loaded; new reviews get more accurate over time.
7. Extensibility. A PreToolUse hook on submit_review can run the team's CI lint as a final check; a custom skill /security-deep can switch the reviewer into paranoid mode; an MCP server can add a query_jira tool for linking issues.
8. Conversation Loop. The loop must handle the user interrupting mid-review ("actually focus on auth") — file reads are cancel-on-interrupt, the synthesis tool is block-on-interrupt (so it finishes the file it's processing). Streaming events show the reviewer's progress through files.
9. Workflow Modes. Plan mode is the default. A separate deep-investigation mode (custom) might be added: when entered, the reviewer disables network tools and is allowed only the local code+tests, to focus the investigation.
10. Task Lifecycle. Sub-agent forks for parallel file review are background tasks: the main reviewer spawns them, continues with synthesis prep, and consumes their task-notifications as they complete. If the user cancels, all forks are stopped and their partial reports preserved.
11. Observability. Per-review cost is tracked; the reviewer surfaces "this review used $0.42, 3 sub-agents" in the final report. A budget cap (maxBudgetUsd: 2.00) prevents one weird PR from consuming a day's budget. The diagnostic event stream records every file read, every classifier decision, every hook execution — letting the team analyze "why was the reviewer slow on PR #1234?"
The 11 dimensions are not separable in practice — they reinforce each other. A reviewer that gets just one dimension right (say, beautiful tool design) but ignores the others ends up unusable. A reviewer that addresses all 11 ships and improves over time.
