agentic developmentcontext files
I let an AI agent build without context. It made a mess.
A simple story about why AI agents need project context before code, and the six-file setup that makes agentic development less chaotic.
6 min read
THE SPEC-DRIVEN AI WORKFLOW
Build with AI
agents
like a senior
engineer.
Stop vibe coding. Learn the 7-step workflow that turns chaotic AI prompts into controlled, spec-driven development — with context files, feature specs, small units, and real verification.
Context files = agent memorySpecs = agent scopeSmall diffs = easy reviewsCursor · Claude Code · Copilot
agentic-dev-playbook
LIVE
The workflow
Spec-driven AI
development
📋 Write a feature spec ✓
🧩 Break into small units ✓
🤖 Agent executes one unit
🔍 Verify + review the diff
🚀 Merge and track progress
The core insight
AI writes fast. Senior engineers make it reliable. This playbook teaches you the difference.
WHY VIBE CODING FAILS
"Vibe coding feels fast until the
codebase starts fighting you."
Most developers start with AI coding tools by typing vague prompts like "build my app." It feels productive at first. Then the codebase becomes messy, features break each other, and the agent starts changing things it should not touch.
6
common failure
patterns
+ 60 more →
1
AI forgets previous decisions
Without context files the agent has no memory of your architecture. It repeats mistakes and breaks patterns you set up earlier.
2
Features drift from the original goal
Vague prompts produce vague results. Without a spec the agent builds something adjacent to what you wanted.
3
Components grow inconsistent
Different sessions, different styles. The codebase starts to look like it was written by ten different developers.
4
Adding features breaks existing ones
When the agent doesn't know the full system, every new feature is a potential regression somewhere else.
5
The agent changes unrelated files
Without scope boundaries the agent edits what it thinks needs fixing — not what you actually asked for.
6
No clear definition of done
Without a verification checklist 'done' means 'it kind of works on my machine' — not reviewed, not tested, not shipped.
Every one of these problems has the same root cause: no system. The fix is not a better prompt — it is giving the AI a workflow to follow.
▶ MISTAKES MIRROR · INTERACTIVE
See if you make these 60 silent killers.
60 confessions
·10 categories·live score
Take the test
THE SOLUTION
Give your AI a system before it writes code.
Agentic Dev Playbook is a practical workflow inspired by modern AI-assisted engineering practices. Senior developers using AI agents don't just prompt — they plan, document, scope, implement, verify, and track.
The formula
Context files
Project memory
Feature specs
Scoped instructions
One unit at a time
Small diffs
Verification
Tests + review
Human review
Architect in control
Progress tracking
Session memory
=
AI-assisted development that stays controlled, consistent, and shippable.
Human is the architect
You own the product, the architecture, the scope, and the final decision. AI executes your specs.
Context before code
Six structured files give the agent memory: what the project is, how it is built, and what the rules are.
Verify before trusting
Tests, typecheck, lint, build, diff review. No AI-generated code ships without a human checking it.
The Workflow
7-step spec-driven AI development flow
Use this as the repeatable loop for any app. The goal is not to prompt harder — it is to give the agent a system to execute.
1
Set Context
2
Write Spec
3
Decompose
4
Verify
5
Ship
1. Clarify before code
Output: Clear product intent and technical boundaries
Beginner meaning
Start with a planning conversation. Do not ask the agent to build immediately.
Senior developer move
Turn the idea into user flows, risks, non-goals, stack decisions, and a smallest shippable version.
Copyable prompt
I have an application idea. Do not write code yet. Idea: <describe in 2-3 sentences> Ask me questions one at a time to clarify: - Core user flows - Technical complexity - Data and storage - Auth/access model - In scope and out of scope - Risks and tradeoffs Push back when something is vague.
Foundation
The six-file context system
Before the coding agent writes code, give it the project memory it needs: product intent, architecture, standards, workflow rules, UI rules, and current progress.
project-overview.md
Product intent
Explains what the app does, who it is for, core user flow, scope, and success criteria.
Starter prompt
Help me write context/project-overview.md for this app. Include: - One paragraph overview - Goals - Core user flow - Feature categories - In scope - Out of scope - Success criteria App idea: <paste your app idea> Make it specific and verifiable.
Specs
Turn features into small buildable units
A spec file replaces a vague prompt. It tells the agent exactly what to build, what not to build, what dependencies are allowed, and how to verify completion.
Feature spec template
# Unit NN: [Feature Name] ## Goal One or two sentences describing the concrete result. ## Design Layout, visual rules, responsive behavior, and UI tokens. ## Implementation ### Component or system area Detailed instructions for what to build. ### Next area Detailed instructions for the next part. ## Dependencies - package-name — why it is needed ## Verify when done - [ ] Feature works within defined scope - [ ] No unrelated files changed - [ ] Tests added or updated - [ ] No TypeScript errors - [ ] No console errors - [ ] Responsive on mobile and desktop - [ ] Build passes
Recommended build plan
Order for building this learning website as a real spec-driven repo.
00
Context foundation
Create context files, AGENTS.md, and repo rules before code.
01
Landing learning shell
Hero, navigation, beginner explanation, and static module cards.
02
Six-file context module
Interactive cards explaining each context file with copy prompts.
03
Spec builder module
Template and example for turning one feature into a Markdown spec.
04
Agent workflow module
Step-by-step loop from context to commit.
05
Prompt library
Copyable prompts for planning, specs, implementation, review, and closure.
06
Repo template section
Show the folder structure users can copy for their own apps.
07
Polish and release
Self-tests, responsive polish, README, and GitHub push.
Prompt Library
Copy the exact prompts for each phase
These prompts are intentionally scoped. They keep the agent in architect-execution mode instead of letting it invent the whole app.
1
Clarify before code
Clear product intent and technical boundaries
2
Create context files
context/ folder and agent entry file
3
Decompose into units
context/specs/00-build-plan.md
4
Write one feature spec
context/specs/NN-feature-name.md
5
Implement only one unit
Small implementation diff with tests
6
Verify and review
Verified diff and review notes
7
Close, commit, continue
Updated tracker and clean commit
AFTER THE PLAYBOOK
What you'll be
able to do
These are the practical outcomes of adopting a spec-driven agentic development workflow — not promises, but natural results of working with AI agents the structured way.
Who this is for
- Beginners using Cursor, Claude Code, or Copilot
- Indie hackers building SaaS products
- Developers frustrated by vibe coding collapse
- Anyone who wants a repeatable AI-agent workflow
OUTCOMES
1
Build with AI agents without losing control of the architecture
2
Avoid the codebase collapse that kills most vibe coding projects
3
Keep components and patterns consistent across the entire codebase
4
Make AI agents respect scope — no more surprise changes to unrelated files
5
Review smaller, focused diffs instead of massive hard-to-audit rewrites
6
Ship faster by eliminating rework caused by vague prompts and missing specs
7
Resume any project in a new AI session using the progress tracker as memory
Template Repo
Use the repo itself as the lesson
The best version of this project is not just a website. It is a working example repo that includes the website, the six context files, specs, and progress tracker.
agentic-dev-playbook/
├── README.md
├── AGENTS.md
├── package.json
├── src/
│ ├── pages/
│ │ └── index.astro
│ ├── components/
│ └── styles/
└── context/
├── project-overview.md
├── architecture.md
├── code-standards.md
├── ai-workflow-rules.md
├── ui-context.md
├── progress-tracker.md
└── specs/
├── 00-build-plan.md
├── 01-landing-learning-shell.md
├── 02-six-file-context-module.md
├── 03-spec-builder-module.md
└── 04-prompt-library-module.md 🎯
One unit at a time
Small, verifiable units are easier to review, test, revert, and improve.
✅
Verification is mandatory
Run checks and review the diff before trusting generated code.
🧠
Progress is memory
Update the tracker after every meaningful change so the next session starts with context.
CREDIBILITY FIRST
What this is — and what it is not
This is not…
-
Magic that removes the need for engineering judgment
-
An AI that builds the whole app while you watch
-
A shortcut that skips planning, specs, or code review
-
A guarantee of any timeline or output quality
-
An endorsement by any specific company or tool vendor
This is…
-
A practical workflow for using AI agents with structure and context
-
A system that keeps humans in control of architecture and decisions
-
A beginner-friendly path to building applications that don't collapse
-
Patterns inspired by how disciplined engineers work with AI tools today
-
A free, open-source playbook you can adapt for any stack or agent tool
No affiliation or endorsement implied. Agentic Dev Playbook is an independent open-source learning resource. Tool names (Cursor, Claude Code, Copilot, etc.) are mentioned for context only.
AVOID THESE
Common AI-agent mistakes
These mistakes make beginners feel fast for one day and slow for one week. Learn to recognise them before they cost you a full refactor.
1
Opening the coding agent before clarifying the product
2
Asking AI to build the whole app in one prompt
3
Skipping context files and expecting the agent to remember
4
Writing vague feature requests instead of scoped specs
5
Mixing UI, database, auth, and background jobs in one unit
6
Accepting code without tests, typecheck, build, or review
7
Not updating progress-tracker.md after implementation
Field notes
Blogs from the messy middle of agentic development
Field notes that teach agentic development and show how Sandip helps teams turn AI-agent ideas into scoped, useful systems.
feature specsAI workflow
The small spec that stopped my AI agent from wandering
How a one-page feature spec turned a vague AI coding request into a calm, reviewable agent task.
7 min read
verificationAI code review
My AI agent kept breaking old code until I made it prove the change
A practical story about adding verification to AI-assisted coding so every agent run ends with evidence, not hope.
6 min read
Planned next posts
How to design an AI agent discovery call for a client project
The beginner-friendly repo template for AI agent projects
Why one task per agent run beats giant prompts
How to review AI-generated pull requests without reading every line twice
The newsletter notes behind a production agent workflow
How to recover when an AI agent deletes the wrong thing
YOUR NEXT STEP
Ready to stop
prompting randomly?
Learn the workflow that turns AI agents into reliable implementation partners. Start with step one: clarify your product idea before writing a single line of code.
Your progress
0 /7
workflow steps completed
Free and open source · No signup required · Works with Cursor, Claude Code, Copilot, Windsurf, and any coding agent