Spec Before Code

Spec Before Code

For non-trivial work, draft a short markdown spec before writing code. Specs prevent over-engineering, surface unknowns, and create a record of why a design was chosen.

When to Write a Spec

Write one when any of these is true:

• Estimated effort > 1 day of work
• Touches authentication, authorization, secrets, PII, or multi-tenant boundaries
• Adds a new service, queue, table, bucket, endpoint, or external integration
• Changes a public API contract (request/response shape, status codes)
• Affects more than one container / service / repo
• The user explicitly asks for a "design doc", "RFC", or "spec"

For everything else (bug fixes, small features, refactors), skip the spec and go straight to implementation — but capture the decision in the PR description.

Folder Layout

specs/
├── README.md                    # Index of specs (one-line summary each)
├── 0001-feature-name.md         # Numbered, kebab-case
├── 0002-another-feature.md
└── archive/                     # Specs whose features have shipped (optional)

Number specs sequentially. Don't reuse numbers.

Spec Template (Use Exactly)

#  — 

**Status:** Draft | In review | Accepted | Implemented | Superseded by #NNNN | Rejected
**Author:** Michel  **Date:**   **Reviewers:** 
**Related:** PBI #, Issue #, Spec #

## Problem

## Goals
- 
- ...

## Non-Goals
- 
- ...

## Constraints
- 

## Proposed Design

### Architecture
```mermaid

Data Model

API / Interface

Failure Modes

Threat Model

Alternatives Considered

1. **** — . Rejected because .
2. **** — ... Rejected because ...

Migration / Rollout

Open Questions

• [ ]
• ...

Test Plan

Success Metrics

## Threat Model — Always Include

Every spec includes a threat model section, even for "boring" features. Use the **STRIDE** framework, or the lighter "assets / actors / threats / mitigations" form below.

```markdown
## Threat Model

### Assets
- 

### Actors / Trust Boundaries
- 
- 

### Threats (STRIDE)
| Category | Threat | Likelihood | Impact | Mitigation |
|---|---|---|---|---|
| Spoofing |  | Low/Med/High | Low/Med/High |  |
| Tampering |  | ... | ... | ... |
| Repudiation |  | ... | ... | ... |
| Information disclosure |  | ... | ... | ... |
| Denial of service |  | ... | ... | ... |
| Elevation of privilege |  | ... | ... | ... |

### Residual Risks

### Secrets & PII
- 
- 

For features with no realistic security surface, you can shorten this to one paragraph — but always include it. The act of writing it forces the question.

Discipline

• Specs are short. Aim for 1–3 pages of markdown. If it's longer, the design probably isn't crisp yet.
• Spec the problem, not just the solution. A spec that skips "Problem" is a recipe for solving the wrong thing.
• Diagram with Mermaid, not ASCII. See the mermaid-diagrams skill.
• Reviewable in a PR. Open the spec as its own small PR before the implementation PR, so the design conversation happens on the spec, not on 800 lines of code.
• Status field is real. Update it as the spec moves through review and implementation.
• Archive after shipping. Move implemented specs to specs/archive/ (or just leave them in place with Status: Implemented) so the history stays.

Anti-Patterns

• Skipping the spec because "it's faster" — and rebuilding twice.
• "Goals" that are just a feature description; missing measurable outcomes.
• Empty "Alternatives Considered" — at least one alternative was real, document it.
• Threat model = "no security implications". Almost never true; force yourself to think about it.
• Spec that becomes stale because nobody updates Status after implementation drifts.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: M2LabOrg
• Source: M2LabOrg/agent-skills
• License: MIT
• Homepage: https://m2laborg.github.io/agent-skills/

Install and usage instructions live in the source repository linked above.