AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

codebase-design

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Original source
mattpocock
License
MIT
Pinned revision
a496f5513d4a4cf889bc48e189e579f4b0bdf6aa

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read mattpocock--codebase-design at revision a496f5513d4a4cf889bc48e189e579f4b0bdf6aa, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 3

DESIGN-IT-TWICE.md

Design It Twice

When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout): your first idea is unlikely to be the best.

Uses the vocabulary in SKILL.md: module, interface, seam, adapter, leverage.

Process

1. Frame the problem space

Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:

  • The constraints any new interface would need to satisfy
  • The dependencies it would rely on, and which category they fall into (see DEEPENING.md)
  • A rough illustrative code sketch to ground the constraints, not a proposal, just a way to make the constraints concrete

Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.

2. Spawn sub-agents

Spawn 3+ sub-agents in parallel, each with a fresh context window. Each must produce a radically different interface for the deepened module.

Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from DEEPENING.md, what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:

  • Agent 1: "Minimize the interface: aim for 1–3 entry points max. Maximise leverage per entry point."
  • Agent 2: "Maximise flexibility: support many use cases and extension."
  • Agent 3: "Optimise for the most common caller: make the default case trivial."
  • Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."

Include both SKILL.md vocabulary and GLOSSARY.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.

Each sub-agent outputs:

  1. Interface (types, methods, params, plus invariants, ordering, error modes)
  2. Usage example showing how callers use it
  3. What the implementation hides behind the seam
  4. Dependency strategy and adapters (see DEEPENING.md)
  5. Trade-offs: where leverage is high, where it's thin

3. Present and compare

Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by depth (leverage at the interface), locality (where change concentrates), and seam placement.

After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated: the user wants a strong read, not a menu.