sdlc-design

name

sdlc-design

description

Use after the spec is clear and before implementation, when a coding task involves real architecture or design trade-offs - data model, API shape, build-vs-buy, a new module, choosing a library, or how the agent's context and guardrails are set up. Make sure to use this whenever you ask "how should we structure this", "what's the architecture", "which library", or faces any non-trivial structural decision, even if he doesn't say "design". Second step of the SDLC loop; skip it for trivial changes.

sdlc-design - decide structure and set the agent's boundaries

Second beat of the SDLC loop. Architecture is the most human part of the lifecycle because it's about trade-offs that depend on context the model can't fully grasp. AI proposes; you decide. This step also configures the harness - the constraints and context the agent will operate inside during implementation.

Why this matters

"AI excels at implementing architectural decisions once they are made." A clear design doc lets the agent scaffold consistently; a missing one lets it improvise structure you'll pay for later. And per the harness lesson, most agent failures are configuration failures - a vague rule or absent guardrail - so defining boundaries here prevents downstream drift.

Procedure

1. Name the trade-offs. Make the real tensions explicit: consistency vs. availability, complexity vs. flexibility, build vs. buy, speed now vs. maintenance later. State which side this decision picks and why.
2. Choose the leanest structure that holds. Echo sdlc-plan's simplification bias: prefer the design with the fewest moving parts that still meets the criteria. Don't add a database, service, or abstraction the spec doesn't require.
3. Set the guardrails. Define what the agent must not do during implementation: files/areas off-limits, patterns to follow, hard constraints. These go into the repo's AGENTS.md / rule file so the harness enforces them.
4. Decide context placement. What belongs in always-on static context (rule files, conventions) vs. loaded on demand (a skill, a reference doc)? Keep static context lean and high-signal.
5. Document the decision. A short ADR-style note so the "why" survives.

Output

## <component> - design note
Decision: <what we're doing>
Trade-offs: <what we gain / give up>
Why this over alternatives: <incl. why not more complex>
Guardrails for the agent: <constraints, off-limits, must-follow patterns>
Context: static (rule file) vs dynamic (skill/ref)

Gate

you approve the design before implementation. Fold the guardrails into the repo AGENTS.md, then hand to sdlc-test.

References

Load these as needed:

• references/tradeoffs-and-guardrails.md - common architecture trade-offs and how to encode guardrails.
• references/context-engineering.md - deciding static vs dynamic context.