How to run a software project with an AI agent — from PRD to production. Use this as a starting point for any project.
PRD / Idea
│
▼
Phase 0 — Discovery & Exploration
├── Read existing docs, explore codebase
├── Ask clarifying questions (what's missing, what's ambiguous)
├── Check what exists vs what needs building
└── Run any existing tools to study actual output/behavior
│
▼
Sprint Planning (docs/sprint-N/)
├── plan.md — Sprint goal, scope, decisions, phasing
├── tasks.md — Task breakdown + difficulty + dependencies + status
├── final-report.md — Final sprint summary + handoff
├── AGENTS.md — Delegation guide (for handing off to another LLM)
└── resources/
├── architecture.md — Tech stack decisions with pros/cons
├── data-design.md — Data models, schemas, API contracts
├── ux-flow.md — Screen designs, user journey (if UI)
└── api-contract.md — REST/API endpoints, request/response shapes
│
▼
Phase 1 → Phase 2 → ... → Phase N
Each phase:
├── 1. Build the code
├── 2. Test it (run it, verify output)
├── 3. Write a phase report (reports/phase-N-report.md)
├── 4. Update tasks.md (mark completed + add findings)
├── 5. Ask for commit confirmation
└── 6. Commit + push
│
├── (when a gnarly bug burns >2 debug cycles) → write an RCA
│ docs/sprint-N/rca/YYYY-MM-DD-<slug>.md
│
▼
Retro / Ideas
└── docs/ideas/future-enhancements.md — backlog for post-MVP
Goal: Understand the problem, the existing codebase, and what needs building.
- Read the PRD — understand the goal, components, dependencies
- Explore existing code — check what's already built, what's missing
- Run existing tools — clone repos, build binaries, test with real data
- Ask clarifying questions — identify gaps, ambiguities, and decisions to make
- Study real output — run scrapers/APIs to understand actual data shapes
- Are there existing repos that need to be cloned? Where?
- What tech stack? Is it decided or needs discussion?
- What's the monorepo structure?
- What's the deployment target? Local? Cloud?
- What data does the system produce/consume?
- What's the MVP scope vs future enhancements?
docs/sprint-N/reports/phase-0-report.md
Containing:
- Manual run instructions
- Test results with real data
- Data structure analysis
- Key findings (surprises, limitations)
- Decisions made
# Sprint-N Plan — <Project Name>
> Status: 🟡 Planning | Created: YYYY-MM-DD
> Companion: [`tasks.md`](./tasks.md) · previous: [`../sprint-<N-1>/final-report.md`](../sprint-<N-1>/final-report.md) · root [`../../AGENTS.md`](../../AGENTS.md)
---
## Context
<What already exists, what the previous sprint delivered, what this sprint builds on.>
## 1. Sprint goal
<One sentence describing what this sprint delivers.>
## 2. Scope
**In scope:**
- ...
**Out of scope:**
- ...
## 3. Key decisions
| Decision | Rationale |
|----------|-----------|
## 4. Phasing
- **Phase 0 — Discovery:** ...
- **Phase 1 — ...:** ...# Task Breakdown — <Project Name>
> Status: 🟡 Planning | Created: YYYY-MM-DD
>
> Status legend: ⬜ pending | 🔵 in_progress | ✅ completed | ❌ blocked
---
## Phase 1 — <Phase Name>
| ID | Task | Difficulty | Dependencies | Status |
|------|--------------------------------|------------|-------------|--------|
| 1.1 | <Task description> | Easy | — | ⬜ |
| 1.2 | <Task description> | Medium | 1.1 | ⬜ |
| 1.3 | <Task description> | Hard | 0.2, 1.2 | ⬜ |
### Service Summary
- **Runtime:** <Python/Node/Go>
- **Files:** `src/a.py`, `src/b.py`
- **Key output:** <what was produced>
> 📄 Full report: [`reports/phase-1-report.md`](./reports/phase-1-report.md)
---
## Dependency Graph
Phase 0 ─────────────────────────────────────┐ 0.1 ──► 0.3 ──► 0.5 │ 0.2 ──► 0.4 │ │ Phase 1 ───────────────────────────────────────┤ 0.2 ──► 1.1 ──► 1.2 ──► 1.5 │
## Summary
| Phase | Tasks | Est. Hours | Status |
|-------------|-------|-----------|--------|
| 0 — Setup | 6 | 1h | ⬜ |
| 1 — Core | 5 | 4h | ⬜ |
| **Total** | **11** | **5h** | |
Rules:
- Every task has an ID, difficulty (Easy/Medium/Hard), dependencies, and status
- Status emoji: ⬜ 🔵 ✅ ❌
- Only one
in_progressat a time - Mark completed when tested AND working
- Add a dependency graph showing the order
- After each phase completes, add a "Service Summary" with key facts
# Architecture — <Project Name>
## 1. Project Structure
project/ ├── services/ │ ├── service-a/ # — │ └── service-b/ # — ├── api/ # Entry point ├── data/ # Shared data (gitignored) └── docs/
## 2. Tech Stack Decisions
### Decision Matrix
| Service | Language | Key Libraries | Why |
|-----------|----------|-------------------|-------------------------------|
| service-a | Node.js | Fastify, Fuse.js | <reason> |
| service-b | Python | pandas | <reason> |
### Why NOT Alternatives
| Rejected | Reason |
|---------------|---------------------------------------|
| Python for X | Would need to port existing library |
## 3. Service Boundaries
### Service-A
- **Input:** <what it receives>
- **Output:** <what it produces>
- **Does NOT:** <responsibilities it avoids>
## 4. Key Architectural Decisions
### Decision 1: <Title>
**Decision:** <What we chose>
**Reasoning:**
- <Point 1>
- <Point 2>
Rules:
- Always explain WHY, not just WHAT
- Include rejected alternatives with reasons
- Document service boundaries (what each service does NOT do)
- Keep it concise — this is for agents to understand context, not a novel
# Data Design — <Project Name>
## 1. Input Data Format
### Source: <API / scraper / CSV>
<description>
| Field | Type | Notes |
|-----------|--------|----------------------|
| field_a | string | |
| field_b | int | |
## 2. Data Pipeline
Raw Data → [Stage 1] → [Stage 2] → Output
### Stage 1 — <Name>
- **Input:** <what>
- **Processing:** <how>
- **Output:** <what>
## 3. Output Schema
```json
{
"field": "value"
}
| Field | Type | Indexed | Notes |
|---|---|---|---|
| id | str | primary | |
| embedding | vector | HNSW | 1024-dim |
**Rules:**
- Show the data at each pipeline stage
- Include actual schema definitions (not just descriptions)
- Note any quirks (duplicate keys, mixed casing, null handling)
- Document what gets embedded vs what goes to metadata
---
### `ux-flow.md` (UI Projects Only)
```markdown
# UX Flow — <Project Name>
## 1. Navigation
Home (/) → Search (/search) → Settings (/settings)
## 2. Screen 1 — <Screen Name>
Behavior:
- <Error/empty states>
1. User lands on Home
2. User types query → navigates to Search
3. Results populate → user filters
4. User clicks item → detail expands
**Rules:**
- ASCII wireframes are good enough — no Figma needed for agent understanding
- Describe behavior, not just layout
- Include all states: loading, empty, error, success
- Show the happy path AND edge cases
---
### `final-report.md`
```markdown
# Sprint N — Final Report
> Status: ✅ Delivered | YYYY-MM-DD
> Audience: sprint-(N+1) context. Read this + [`AGENTS.md`](../../AGENTS.md) before starting sprint-(N+1).
---
## 1. Sprint goal & outcome
<What we set out to build and what was delivered.>
## 2. Final structure
| Item | Count | Notes |
|---|
| Decision | Rationale |
|---|
| Phase | Tasks | Status |
|---|
📄 Full reports:
reports/
<commands><What the next sprint needs to know — integration points, unresolved items, data dependencies.>
### `AGENTS.md` (For Delegating to Another LLM)
This is the most critical document. It's a self-contained implementation guide.
```markdown
# AGENTS.md — <Sprint Name> Implementation Guide
> **For:** Any LLM agent implementing <project>.
> **Context:** <what was already built, what exists, what NOT to rebuild>
---
## 0. What Already Exists (Do NOT Rebuild)
Endpoints ready to use:
POST /search—GET /health—
| Layer | Technology |
|---|---|
| Frontend | Astro + React |
| Styling | Tailwind CSS |
<directory tree of files the agent must create>
<numbered list of steps, each with brief code snippet if critical>
Code snippet showing the exact pattern:
function ComponentName({ props }: Props) {
// implementation hint
}interface RequestType { ... }
interface ResponseType { ... }| Source | What to Copy |
|---|---|
| path/to/file | pattern to reuse |
| Reference | This Project | Why |
|---|
- Task 1
- Task 2
cd service && npm run dev- <Checklist of what "done" looks like>
**Rules for AGENTS.md:**
- Include EXACT code snippets for critical logic
- List reference files the agent can copy-paste from
- Include a numbered checklist — agents follow checklists better than prose
- Mention what NOT to do (deviations from reference)
- Include "Done Criteria" so the agent can self-validate
---
### `reports/phase-N-report.md` (Per-Phase Report)
```markdown
# Phase N Report — <Phase Name>
> Completed: YYYY-MM-DD
---
## 1. How to Run
```bash
<exact commands to run this phase>
<diagram showing component layout>
| Metric | Value |
|---|---|
| ... | ... |
| Decision | Reason |
|---|
| File | Purpose |
|---|---|
| ... | ... |
### `rca/YYYY-MM-DD-<slug>.md` (Root Cause Analysis)
Write one **whenever a non-trivial bug burns more than ~2 debug cycles** (or
anything in prod breaks) — not for trivial fixes, but for the gnarly ones where
"what we thought was the cause wasn't." File under the **current sprint** at
`docs/sprint-N/rca/YYYY-MM-DD-<short-slug>.md`.
````markdown
# RCA — <one-line description>
> **Date:** YYYY-MM-DD · **Severity:** Low/Med/High · **Component:** <where>
> **Status:** ✅ Resolved
## 1. Summary
<2-3 sentences: what happened + the ACTUAL root cause, up top. No burying the lede.>
## 2. Impact
<who/what affected, data or prod impact, duration>
## 3. Symptoms (observed)
| Signal | Value |
|---|---|
## 4. Timeline
| # | Attempt | Outcome | Verdict |
|---|---------|---------|---------|
| 1 | <what we tried> | <result> | real fix / red herring / the cause |
## 5. Root cause
<The actual cause + evidence (file/line, sizes, logs). Be concrete.>
## 6. The fix
```diff
- <before>
+ <after>
| Metric | Before | After |
|---|
<misleading signals, red herrings, what masked the real cause>
- <preventive change / process tweak>
<doc URLs, issue links, file paths>
**Rules for RCA:**
- **Lead with the root cause** in the Summary — don't make the reader wait.
- **Tag every Timeline row** (*real fix* / *red herring* / *the cause*) — the red herrings are the most valuable part for future-you.
- **Capture the symptom signature** (e.g., "X loads 200 but doesn't apply") so the same class of bug is recognizable next time.
- Write it **the same day**, while the debug trail is fresh.
- File under `docs/sprint-N/rca/YYYY-MM-DD-<slug>.md`
> **Note:** `architecture.md`, `data-design.md`, `ux-flow.md`, and `api-contract.md`
> live inside `docs/sprint-N/resources/`. Only `plan.md`, `tasks.md`,
> `final-report.md`, and `AGENTS.md` sit at the sprint root.
---
## 4. Communication Patterns
### Do
- **Ask before committing** — "Confirm and I'll commit"
- **Ask before design decisions** — "Here's my recommendation, thoughts?"
- **Break down tasks before building** — "Let me split this into smaller tasks"
- **Test immediately after building** — run the code, show the output
- **Update docs after every phase** — report + tasks.md update
- **Document findings, not just results** — what surprised you, what failed
- **Write an RCA for gnarly bugs** — if a bug burns >~2 debug cycles (or breaks prod), file `docs/sprint-N/rca/YYYY-MM-DD-<slug>.md`; lead with the root cause and tag red herrings
### Don't
- Never commit without confirmation
- Never assume a library is available — check first
- Never skip the "study real output" step in Phase 0
- Never leave broken tasks marked as ✅
- Never skip writing the phase report
- **Never keep blind-guessing on a stuck bug** — after ~2 failed attempts, stop and read the actual docs/issues/canonical source, then write an RCA
---
## 5. Difficulty Levels
| Level | Meaning | Example |
|--------|--------------------------------------------------|--------------------------------------------|
| Easy | ≤30 min, no unknowns, mostly wiring | "Add endpoint", "Create file structure" |
| Medium | 1-2h, some design decisions, integration work | "Build wrapper", "Normalize data" |
| Hard | 3h+, complex logic, multiple edge cases | "Facility extraction", "SSE streaming" |
---
## 6. Startup Checklist (New Project)
When starting a new project with this workflow:
1. [ ] Create the monorepo structure
2. [ ] Write the PRD or confirm existing one
3. [ ] Run Phase 0 — clone deps, test tools, study real output
4. [ ] Create `docs/sprint-1/` with all planning docs
5. [ ] Break tasks into phases with difficulty + dependencies
6. [ ] Start Phase 1 — build → test → report → commit
7. [ ] After each phase, update `tasks.md` and write `reports/phase-N-report.md`
8. [ ] When delegating, create `AGENTS.md` with checklist + code snippets
9. [ ] After sprint, write `docs/ideas/future-enhancements.md` for backlog
---
## 7. Complete Directory Structure
```
project/
├── docs/
│ ├── prd.md # Original requirements
│ ├── ideas/
│ │ └── future-enhancements.md # Backlog for later
│ └── sprint-<N>/
│ ├── plan.md # Sprint goal, scope, decisions, phasing
│ ├── tasks.md # Task breakdown + status
│ ├── final-report.md # Final sprint summary + handoff
│ ├── AGENTS.md # Delegation guide
│ ├── reports/
│ │ ├── phase-0-report.md # Discovery findings
│ │ ├── phase-1-report.md # Per-phase reports
│ │ └── ...
│ ├── resources/
│ │ ├── architecture.md # Tech decisions + structure
│ │ ├── data-design.md # Schemas + pipelines
│ │ ├── ux-flow.md # Screens + interaction (UI projects)
│ │ └── api-contract.md # REST endpoints + shapes
│ └── rca/ # Root-cause analyses
├── services/ # Monorepo services
├── api/ # API layer
├── web/ # Frontend (if applicable)
├── data/ # Runtime data (gitignored)
└── .gitignore
```
---