MD-First Development
Write a markdown spec before writing any code. Every component, every page, every feature starts with a .md file — living alongside the code it describes.
Why Specs First?
AI tools hallucinate when they lack context. A spec file gives the AI everything it needs before it touches a single line of code: purpose, responsibilities, props, logic, and dependencies. The result is more accurate output, fewer corrections, and a codebase that documents itself.
The 3-Level Hierarchy
Specs exist at three levels. Each level answers a different question.
Level 1 — Architecture
How the system is structured and how the main parts connect.
→ docs/architecture.md
Level 2 — Page / Feature
What this page does, its folder structure, and the components it uses.
→ src/app/dashboard/Dashboard.md
Level 3 — Component
Granular logic and responsibilities of a single component.
→ src/components/Button/Button.mdLevel 1
Architecture
System-wide view. How services, apps, and modules relate. Written once, updated when structure changes.
Level 2
Page / Feature
One spec per page or feature. Includes the folder structure and a map of which components are used and why.
Level 3
Component
One spec per component, colocated in the same folder. Purpose, props, logic, and dependencies.
Level 2: The Page Spec
When a page is made up of multiple components, the page spec does two things: it describes what the page does and maps out the folder structure with links to each component spec. This gives the AI a complete picture before it touches a single component.
src/app/dashboard/Dashboard.md
# Dashboard Page
## Purpose
Main authenticated view. Shows account summary, recent activity, and quick actions.
## Folder Structure
dashboard/
Dashboard.md ← this file
Dashboard.tsx ← page shell, layout only
components/
SummaryCard/
SummaryCard.md ← see component spec
SummaryCard.tsx
ActivityFeed/
ActivityFeed.md ← see component spec
ActivityFeed.tsx
QuickActions/
QuickActions.md ← see component spec
QuickActions.tsx
## Components Used
- SummaryCard — displays key account metrics (balance, usage, alerts)
- ActivityFeed — paginated list of recent events, sorted newest first
- QuickActions — fixed set of shortcut buttons, role-dependent visibility
## Data
Fetches from /api/dashboard on mount. Passes slices to each component.
No component fetches independently.The folder structure in the page spec is the blueprint. When the AI generates or modifies components, it already knows what else lives in that folder and how they relate.
Level 3: The Component Spec
Each component spec lives in the same folder as the component. It is written before any code is created.
src/components/SummaryCard/SummaryCard.md
# SummaryCard ## Purpose Displays a single account metric with label, value, and an optional alert indicator. ## Responsibilities Owns: - Rendering the metric value with correct formatting (currency, %, count) - Showing an alert badge when value exceeds threshold Does NOT own: - Fetching data (receives props only) - Navigation (parent handles clicks) ## Props / API | Name | Type | Required | Description | |-----------|-----------|----------|---------------------------------| | label | string | Yes | Metric label shown above value | | value | number | Yes | Raw numeric value | | format | 'currency' | 'percent' | 'count' | No | Display format | | alert | boolean | No | Show alert badge when true | ## Logic & Behavior - value is always formatted before display — never render raw numbers - alert badge appears top-right, red, only when alert=true - No click handler on the card itself; parent wraps in a link if needed ## Dependencies - formatValue utility (lib/format.ts) - Used by: Dashboard
What It Looks Like in Practice
Every folder that contains code also contains a spec. The .md file and the implementation file are always siblings.
docs/ └── architecture.md ← Level 1 spec (system) src/ ├── app/ │ └── dashboard/ │ ├── Dashboard.md ← Level 2 spec (page) │ ├── Dashboard.tsx │ └── components/ │ ├── SummaryCard/ │ │ ├── SummaryCard.md ← Level 3 spec (component) │ │ ├── SummaryCard.tsx │ │ └── SummaryCard.test.tsx │ ├── ActivityFeed/ │ │ ├── ActivityFeed.md │ │ ├── ActivityFeed.tsx │ │ └── ActivityFeed.test.tsx │ └── QuickActions/ │ ├── QuickActions.md │ ├── QuickActions.tsx │ └── QuickActions.test.tsx
The Workflow
1. Write the page spec first
Define what the page does and sketch the folder structure with component names. Use create-feature to scaffold it from the template. You don't need all the details — just enough to map the shape of the work.
2. Write each component spec
For each component referenced in the page spec, create a colocated ComponentName.md. Use the /spec command to scaffold it from the template.
3. Review before coding
Read through the specs as a team (or alone). Catch misunderstandings in markdown before they become bugs in code.
4. Generate code from the spec
Use create-component to scaffold implementation. The command reads the spec and uses it as the source of truth for props, tests, and behavior — no re-explaining required.
Commands
Level 2
create-feature
Scaffold a page or feature spec (Level 2). Creates FeatureName/FeatureName.md from the feature template and waits for approval before writing any code.
Create a Dashboard feature with summary, activity feed, and quick actions
Level 3
/spec
Create a component spec before writing any code. Scaffolds ComponentName/ComponentName.md from the template and waits for your approval.
/spec SummaryCard — shows a metric with label, value, optional alert
Level 3
create-component
Scaffold the implementation. Checks for an existing spec first — if none exists, drafts one before touching any code.
Create a SummaryCard component
Generating Docs
Once code exists, these three commands generate documentation at each level of the hierarchy — automatically tailored to your project's stack (React, Vue, Go, Python, and more).
Level 1 /doc-arch → docs/architecture.md Level 2 /doc-feature → docs/features/<name>.md Level 3 /doc-component → <path>/<name>.md (colocated)
Level 1
/doc-arch
Generates or updates docs/architecture.md — system overview, key flows, Mermaid diagrams, and architecture decisions.
/doc-arch /doc-arch 142 # from PR #142
Level 2
/doc-feature
Generates or updates docs/features/<name>.md — purpose, components used, data flow, and user flows for a specific feature area.
/doc-feature auth /doc-feature apps/billing
Level 3
/doc-component
Creates a colocated <name>.md next to the target file — API/props, usage example, behavior, and edge cases.
/doc-component src/components/Button.tsx /doc-component lib/utils/parser.js
When to use which
| Scenario | Command |
|---|---|
| Merged a PR that changed system boundaries or added a service | /doc-arch |
| Shipped a new feature — want to document how it works end-to-end | /doc-feature |
| Wrote a new component, utility, or module | /doc-component |
| Reviewing a PR and want to understand architecture impact | /doc-arch <PR number> |
| Backfilling docs on existing code | /doc-component <path> |
Squad integration
When using the squad pipeline (/squad-auto), the Doc Writer step (/squad-doc) generates companion docs automatically after review passes — you don't need to run these commands manually after a squad task. Use them directly when patching code outside the pipeline, backfilling docs, or documenting a PR from another team.
The Rule
If a folder contains a .tsx (or .jsx, .vue, .svelte) file, it should also contain a .md spec. No exceptions. The spec doesn't need to be long — a clear Purpose and Responsibilities section is enough to give the AI meaningful context.
Was this helpful?
Help us improve the documentation by sharing your feedback.