Skip to content

stevesolun/ctx / .agents/skills/codebase-design

codebase-design

Verified

Design 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.

FileKindSize
DEEPENING.mdmarkdown2.2 KB
DESIGN-IT-TWICE.mdmarkdown2.2 KB
SKILL.mdskill md2.6 KB
agents/openai.yamlconfig102 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.
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall