stevesolun/ctx / .agents/skills/codebase-design
codebase-design
VerifiedDesign or improve module interfaces using deep-module heuristics. Use when deciding where a seam belongs, reducing caller-facing complexity, improving testability or navigability, or comparing module designs.
| File | Kind | Size |
|---|---|---|
| DEEPENING.md | markdown | 2.2 KB |
| DESIGN-IT-TWICE.md | markdown | 2.2 KB |
| SKILL.md | skill md | 2.6 KB |
| agents/openai.yaml | config | 102 B |
DESIGN-IT-TWICE.md
View on GitHub# Design It Twice
When materially different interfaces are plausible, compare more than one
design. Parallel agents can accelerate independent exploration, but local
sketches are enough for a small problem.
Uses the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
## Process
### 1. Frame the problem space
Before exploring alternatives, frame the problem space:
- 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
Share the framing when user feedback would materially improve the design.
### 2. Explore alternatives
Produce two or more meaningfully different interfaces. Use parallel sub-agents
when the alternatives divide cleanly and the expected insight exceeds
coordination cost. Otherwise sketch them locally.
Give each exploration the same constraints and a distinct optimization target,
for example:
- 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 and adapters for
cross-seam dependencies."
Use the project's vocabulary. The terms in [SKILL.md](SKILL.md) are lenses, not a
required replacement for established domain language.
For each alternative, capture:
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 the designs at a level proportional to the decision. Compare **depth**,
**locality**, **seam placement**, migration cost, and fit with existing code.
Recommend the strongest design and explain its trade-offs. Propose a hybrid only
when it is more coherent than either source design.
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 |