AI made generation cheap. Without intent, that speed becomes noise. With intent, it becomes clarity.
Without Intent
AI chooses a stack you never asked for
AI invents a timeline nobody needs
AI bloats specs, stories, and process
8 files, 3,740 lines, 132KB of noise
You still don't know what should exist
With Intent
Why: why this must exist
What: what must be true
Not: where AI cannot go
1 file, 47 lines, signal
AI executes instead of guessing
02 — The Framework
An Intent Document has three sections. No extras. No changelog.
Why
Why does this exist?
State the problem, goal, and success bar. If this changes, the intent changed.
What
What are we building?
State features, flows, and edge cases. Stay concrete, but never prescribe stack, architecture, or timeline.
Not
What will we never do?
State the lines AI cannot cross. Scope limits, security rules, quality bars, forbidden moves.
Evolve
Where do learnings go?
Into Why, What, and Not themselves. A learning that matters rewrites a line; a learning that rewrites nothing does not matter yet. INTENT.md always shows current intent. The commit message records why it changed.
03 — The Lifecycle
Intent is not static. Every experiment rewrites Why / What / Not until they stop moving, or evidence ends them.
seed
→
exploring
→
clarified
→
build
dropped
← any state can end here. Good.
# INTENT.md# INTENT — Legacy Converter
> status: exploring## WhyProblem: Legacy projects can't leverage vibe coding.
Hypothesis: Generating a CLAUDE.md is the missing bridge.
Validation: Convert one typed project, measure dev speed.
## What
- [ ] Scan legacy codebase structure
- [ ] Generate vibe-coding-ready CLAUDE.md
- [ ] Report type coverage as a readiness score
## NotForbidden: Never modify source files without explicit confirmation
Scope: TypeScript only for now
Out of scope: Automated refactoring suggestions
# git log --oneline INTENT.md — the history of intent, outside the filee41a9c2 Not: drop refactoring suggestions (interviews: nobody trusted them)
7b03d5f Why: CLAUDE.md generation is the bridge (interviews: most requested)
2c8f1e0 What: add readiness score (prototype v1: type coverage was the key signal)
04 — The Pipeline
Humans define intent and judge outcomes. AI does the rest.
✍
Write Intent
Write Why / What / Not
Human
⚙
Generate Spec
AI turns intent into tasks
AI
💻
Implement
AI agents write the code
AI
🔍
Verify
AI reviews, tests, and lint-checks
AI
🚀
Deploy
CI/CD pushes to production
AI
💡
Learn & Decide
Review results. Update intent or drop it
Human
05 — Principles
Four rules. Break them and AI starts guessing.
Never write How
Intent sets constraints, not implementation. Write "no external cache layer," not "use Redis."
Admit uncertainty
Mark unknowns with (?). Honest uncertainty beats fake precision.
Drop fast
If the idea is dead, set status to dropped and say why in the commit. A dropped intent saves future time.
Intent precision = output quality
"Build a good app" is noise. "New users reach value in 30 seconds" is intent.