Lightweight Design Doc
Use this for features, enhancements, or non-trivial changes to existing projects. If you’re building a new platform, doing a major migration, or making decisions with broad architectural impact, use the full TDD template instead.
| Field | Value |
|---|---|
| Title | |
| Author | |
| Date | |
| Status | Draft / In Review / Approved |
| Linear Issue | |
| Team | Data / AI & Platform |
1. What and Why
What are we doing? One paragraph. What’s being built or changed, and for whom.
Why are we doing it? The business or user problem this solves. Link to the PRD, ticket, or client request if one exists.
2. How It Works Today
Brief description of the current behavior or system state relevant to this change. Skip if greenfield feature with no predecessor.
3. Proposed Change
Describe what you’re going to build or change. Be specific enough that another engineer could review your approach.
- Approach — what you’ll do, at a high level.
- Key components touched — which services, models, tables, workflows, or UI areas change.
- New dependencies — any new libraries, APIs, providers, or services introduced.
Include a diagram if the change involves multiple components or a non-obvious flow. Otherwise, skip it.
4. Alternatives Considered
What other approaches did you think about? Why did you pick this one? If the choice is obvious and there’s only one reasonable path, say so and move on.
| Option | Pros | Cons | Verdict |
|---|---|---|---|
| … | … | … | Selected / Rejected |
5. Risks and Open Questions
- Risks — what could go wrong, what’s the blast radius, any backward-compatibility concerns.
- Open questions — anything you’re unsure about that needs input before or during implementation.
6. Test Plan
How will you know this works? Be concrete.
- Unit tests for …
- Manual QA of …
- Integration test covering …
- Eval run on … (if AI component)
7. Rollout Plan
How does this get to production?
- Deploy strategy — feature flag, staged rollout, direct deploy, etc.
- Rollback plan — what you do if it breaks.
- Monitoring — what to watch after deploy (errors, latency, cost, etc.).
For trivial changes, “deploy and monitor error rates” is a fine answer.
8. Decisions Made
Record any non-obvious choices made during implementation. Future-you will thank present-you.
| Decision | Why | Date |
|---|---|---|
| … | … | … |
9. Agent Implementation Context
Purpose: This section turns the design doc into a useful starting point for AI coding agents (Cursor Plan Mode, Codex, etc.). Fill this out after the design is approved and before handing off to an agent. You can paste this entire doc as context, or just sections 3 + 9.
Codebase Orientation
- Repo(s):
<repo name and path> - Key files / entry points:
path/to/relevant/file.ts— what it doespath/to/another/file.py— what it does
- Reference implementation: Point to an existing feature or pattern in the codebase that this work should follow. “See how X was built in
path/to/example” is the single most useful thing you can give an agent.
Implementation Sequence
Ordered list of what to build, in what order. Each step should be independently testable.
- …
- …
- …
Acceptance Criteria
Concrete, verifiable statements. An agent (or a human) should be able to check each one off.
- …
- …
- …
Constraints and Guardrails
What the agent should NOT do, and boundaries it should stay within.
- Don’t touch: files, services, or areas that are out of scope
- Must use: specific libraries, patterns, or conventions required
- Must not: any hard constraints (e.g., no new dependencies, don’t change the DB schema, don’t modify shared types)
- Style / conventions: naming patterns, file organization, or code style to follow