BuhDuy256/deck-agent / .agents/skills/codebase-design
codebase-design
VerifiedShared 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.
| File | Kind | Size |
|---|---|---|
| DEEPENING.md | markdown | 2.6 KB |
| DESIGN-IT-TWICE.md | markdown | 2.9 KB |
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 6.8 KB |
| agents/openai.yaml | config | 102 B |
DESIGN-IT-TWICE.md
View on GitHub# Design It Twice
When the user wants to explore alternative interfaces for a chosen deepening candidate, compare alternatives sequentially by default. Use parallel sub-agents only when supported and explicitly authorized for the task. Based on "Design It Twice" (Ousterhout): your first idea is unlikely to be the best.
Uses the vocabulary in [SKILL.md](SKILL.md): **module**, **interface**, **seam**, **adapter**, **leverage**.
## Process
### 1. Frame the problem space
Before exploring alternatives, 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](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. Explore proposals while the user considers the explanation. Pause implementation of system-wide choices until the owner decides, as required by AGENTS.md.
### 2. Explore alternatives
Produce contrasting interfaces sequentially. If task-authorized delegation is available, distribute alternatives within the available agent limit. Each alternative should use a materially different design constraint.
Frame each alternative with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Use a different design constraint for each alternative:
- Alternative 1: "Minimize the interface: aim for 1–3 entry points max. Maximise leverage per entry point."
- Alternative 2: "Maximise flexibility: support many use cases and extension."
- Alternative 3: "Optimise for the most common caller: make the default case trivial."
- Alternative 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
Include both [SKILL.md](SKILL.md) vocabulary and CONTEXT.md vocabulary in the brief so each alternative names things consistently with the architecture language and the project's domain language.
Each alternative includes:
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](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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |