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 four sections. No extras.
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.
Learnings
What did we discover?
Log what you tried, what you learned, and what changed. This is how intent gets sharper.
03 — The Lifecycle
Intent is not static. It sharpens through learning or dies on evidence.
seed
→
exploring
→
clarified
→
build
killed
← any state can end here. Good.
# INTENT.md# INTENT — Legacy Converter
> status: exploring## WhyProblem: Legacy projects can't leverage vibe coding.
Hypothesis: An automated converter can bridge the gap.
Validation: Convert one small project, measure dev speed.
## What
- [ ] Scan legacy codebase structure
- [ ] Generate vibe-coding-ready CLAUDE.md
- [ ] Suggest refactoring candidates
## NotForbidden: Never modify source files without explicit confirmation
Scope: Node.js/TS only for now
## Learnings[2026-04-01] Prototype v1 — type coverage was the key signal
[2026-04-05] User interview — they want CLAUDE.md generation most
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 kill 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.
Kill fast
If the idea is dead, say so and record why. A killed intent saves future time.
Intent precision = output quality
"Build a good app" is noise. "New users reach value in 30 seconds" is intent.