Most AI-assisted development workflows treat the spec as a means to an end: you write it, you get code, you move on. The spec is scaffolding, discarded once the structure stands. That is a significant waste. A spec maintained through the full lifecycle of a project is a technical document, an onboarding resource, a basis for help texts and user documentation, and — after launch — the only reliable record of why the code is the way it is.
This article walks through the phases where Markdown earns its value, the concept of slices that bridges planning and implementation, and three concrete prompts you can take directly into your next project.
The phases
The phases below are not unique to spec-driven development — they map to how most software projects are structured. What is different is the emphasis on maintaining Markdown documents as the primary artefact through each phase, with each document feeding the next.
| Phase | What happens | Markdown output | |
|---|---|---|---|
| 1 | Idea | Develop the concept in a chat session. Explore approaches, frameworks, constraints. When you have a workable foundation, export the conversation to Markdown. | idea.md |
| 2 | Information gathering | Collect everything that defines the problem domain: business rules, existing systems, requirements from a client or your own research. This material becomes reusable context — a lightweight RAG layer — for every phase that follows. | domain.md business-rules.md |
| 3 | Explorative | With your gathered material loaded, use AI to explore the solution space: architectures, data models, user flows. No commitments yet. The goal is to arrive at a well-understood problem before specifying anything. | exploration-notes.md |
| 4 | Specification | The most demanding phase. You prompt the spec into existence — data definitions, business logic, structural decisions, API shapes — without writing code. The result is a complete technical description of what will be built. | specification.md |
| 5 | Planning | Turn the specification into a development plan: in what order things will be built, what methodology applies, how testing will work. The plan references the spec but is separate from it. | implementation-plan.md |
| 6 | Slices | The plan is broken into discrete, AI-codeable units — slices. Each slice is small enough to implement and validate in one round. AI generates the slices from the plan; you review and sequence them. | slices.md |
| 7 | Development | Implement slice by slice. Between slices: validate against the spec, run tests, review code. Update documentation whenever the implementation diverges from the plan — which it will. | specification.md (updated) dev-log.md |
| 8 | Documentation | Export user-facing material — help texts, manuals, release notes — from the accumulated Markdown. Different roles can receive different extracts: the project manager gets a summary, the BI analyst gets the data model, the end user gets the help text. | help.md → Word/PDF |
| 9 | Maintenance | Changes and new features are never written into existing documentation. They go into a separate updates folder. During implementation, the main documentation is updated in parallel. This keeps the documentation honest without rewriting history. | updates/feature-x.md |
Context is cumulative
The most important property of this workflow is that context accumulates. Each phase produces a document that the next phase reads. By the time you reach development, the AI agent working on your codebase has access to a full history of the decisions that led to the current structure — not as chat history, which expires, but as persistent Markdown files it can reference at any point.
Every prompt you write carries the weight of every document that came before it. The quality of the context determines the quality of the output — at every phase, not just in development.
A practical consideration: you probably don't want to feed all of this context to the coding agent at once. Early-phase material — the idea exploration, the business domain notes — can become noise for an agent focused on implementing a specific module. A workable structure is three overlapping layers: the business/domain documents inform the specification, the specification informs the codebase, and the codebase sits in a separate context from the early material. The specification acts as the bridge.
This is closely related to the pattern of using Markdown as a lightweight context layer for AI agents generally — covered in more depth in Markdown as RAG.
Slices — bridging planning and code
The gap between a development plan and working code is where most AI-assisted projects lose coherence. "Implement the booking system" is not a prompt — it is an invitation for the model to make every architectural decision that the specification carefully avoided leaving open.
Slices solve this. A slice is a unit of implementation small enough that an AI coding agent can complete it in one focused round, validate it against the spec, and leave the codebase in a clean state before the next slice begins. Each slice has a defined scope, a set of acceptance criteria, and an explicit list of what must not be changed.
You don't write the slices manually. You ask AI to generate them from the implementation plan — and then you review and sequence them. The second prompt below shows exactly how to do this.
It is worth maintaining a development log — a Markdown file updated continuously during implementation — for areas where you anticipate difficulty, or where difficulty emerges. The value is not debugging; it is memory. Knowing what was tried and ruled out before is information the next agent session — or the next developer — cannot reconstruct from code alone.
Keep the log lean. A log that becomes exhaustive becomes noise. One line per significant decision or dead end is enough.
After launch: documentation changes role
This is the insight that makes the difference between a project that can be maintained and one that gradually becomes opaque.
Before launch, the specification is a target — it describes what the software will do. After launch, the same document is a record — it describes what the software does. These are different things, and conflating them is where documentation typically fails.
The practical solution: never modify the main specification to accommodate new features or changes. New work goes into a separate folder — call it updates/ — with one file per change or feature. During development of that change, the main specification is updated in parallel. The update file is the working document; the specification is the settled truth.
This means the specification always reflects the current state of the software, never a mixture of past plans and future intentions. An AI agent picking up work on the codebase reads the specification and gets an accurate picture — not a document that was written two years ago and partially reflects things that were later changed.
After launch, documentation stops being a plan and starts being a memory. A memory that goes stale is worse than no memory at all — because it misleads rather than informs.
Three prompts to use today
The following prompts are ready to use. Adjust the file references to match your own project structure.
1 — The decision prompt
Use this whenever a question produces a long answer with multiple options. It forces the model to weight the alternatives and commit to a recommendation — rather than producing a list that leaves every decision to you.
If multiple choices exist, ask me to choose instead of listing everything. When asking me to choose: - Ask the question with necessary context first. - If the decision is non-trivial, you MAY add brief headline-based explanations (one per option, short, factual — only when genuinely helpful). - Immediately include a table with: Option | Short label | Pros/Cons (brief) | Weight (0–100%) - Keep pros/cons concise. - End with: recommend at most one option, or say "no clear recommendation".
This works best as a persistent system prompt. Add it to your AI tool's configuration so it applies to every conversation — not just when you remember to ask for it.
2 — The slices prompt
Use this to break a section of your implementation plan into discrete, AI-codeable units. Run it once per planned section, not once for the whole project.
ROLE: You are a senior software architect and AI coding-agent planner. CONTEXT: Read the repository before proposing slices. Use these files as the main source of truth: - docs/specification.md - docs/implementation-plan.md TASK: Take the selected section from docs/implementation-plan.md and break it down into small implementation slices suitable for a code-generating AI agent. EACH SLICE SHOULD INCLUDE: - Goal - Scope - Likely files / components affected - Acceptance criteria - Suggested tests - Constraints: what must not be changed IMPORTANT: Base the slices on the existing repository structure. Do not redesign the solution. Do not invent requirements not found in the specification or plan. Keep each slice small enough for one focused implementation round. SELECTED PLAN SECTION: [paste or name the section here]
3 — The best-practice prompt
Use this early in the specification phase to establish an architectural baseline. Note: AI tools tend toward agreement, particularly if you propose something yourself. Push back. Ask the model to argue against its own recommendation before you accept it.
ROLE: You are a senior [your stack] architect. CONTEXT: Read the existing project context before answering. Use these files as the main source of truth: - docs/project-overview.md - docs/current-architecture.md - docs/business-rules.md CASE: [One paragraph describing the system, team size, and constraints.] TASK: What is best practice for the [backend / frontend / data model / integration layer] architecture in this type of project? IMPORTANT: Base the answer on the existing context. Keep it practical and suitable for the team size described. Avoid over-engineering. After giving your recommendation, argue briefly against it — what are the strongest reasons not to follow this approach?
One workflow, start to finish
The value of spec-driven development compounds across phases. The idea document feeds the specification. The specification feeds the plan. The plan produces slices. The slices guide implementation. After launch, the specification becomes the memory that makes maintenance coherent rather than archaeological.
At every stage, Markdown is the connective tissue — not because of any specific feature, but because it is plain text that both humans and AI read without translation. The spec you write in phase four is the same file the coding agent reads in phase seven. Nothing is lost between the intent and the implementation.
Start small: pick a current project, write a specification.md for the next feature, and run it through the slices prompt. The three prompts above work independently of each other — you don't need to adopt the whole workflow at once to see the benefit.
Related reading: Spec-driven development — this is where Markdown really shines · Markdown as RAG — your own lightweight context layer · Which Markdown flavor for AI?
Further reading: Spec-driven development — this is where Markdown really shines · Markdown as RAG — your own lightweight context layer · Build your own coding agent