Why use many docs when one (plan) doc does the trick?

After many years of verbose PRDs that few people read a second time or maintain, I discovered a better way. Instead of splitting planning across multiple documents that quickly drift out of sync, we now use one living plan document that serves both humans and AI throughout the entire feature specification and development process.

This approach has transformed how our team collaborates. Here's why it works and how it compares to other structured planning methods.

The Multi-Document Problem: Pre-AI and AI-Era Approaches

Traditional product development has always generated a proliferation of documents. Before AI tools became common, teams would create:

• Product Requirements Document (PRD) written by the PM, describing what needs to be built from a business perspective.
• Engineering Requirements Documents (ERDs) rewriting the PMs requirements into the technical equivalent
• Design Document created by engineering, explaining how it will be built.
• Architecture diagrams living in separate files or tools.
• Test plans maintained by QA in yet another location.
• API specifications documented separately from everything else.

The classic pattern was painfully familiar: someone (usually a PM or tech lead) would spend days crafting comprehensive documentation. The team would read it once during kickoff, maybe ask a few questions, translate it into their documents, and then... it would gather digital dust.

By week two of development, the PRD was already outdated. Engineers would make reasonable technical decisions that affected the product approach, but updating the PRD seemed like bureaucratic overhead. The architecture doc would fall behind as the team discovered better patterns. The ERD would be abandoned entirely after the first schema migration.

Three months later, you'd have a folder full of documents that told different stories about different points in time. None of them reflected what you actually built or why. New team members would ask "which doc is current?" and the answer was always "well, read the code and ask around."

The AI-Era Multi-Document Approaches

With AI assistance, sophisticated planning frameworks like BMAD (Breakthrough Method for Agile AI-Driven Development) and GitHub's Spec Kit have emerged to help teams generate better documentation faster.

These approaches are thoughtful and structured. BMAD creates core planning documents (PRD, Architecture, optional UX and Brief), but then shards them into many smaller files: individual epics, user stories, risk assessments, quality gates, test design documents, and traceability matrices. A modest project can easily generate 10-20+ files across these categories.

Spec Kit takes a different approach, generating 5 core documents: constitution.md (project principles), spec.md (features and user flows), plan.md (implementation details with architecture), tasks.md (actionable work breakdown), and quickstart.md, plus validation reports from analyze and clarify commands.

AI makes creating these documents easier—you can draft comprehensive specifications in hours instead of days. But it doesn't solve the fundamental problems that plagued documentation in the pre-AI era:

• The reading problem persists: People still don't read multiple documents, even when AI helped generate them. Engineers read the technical ones but skip product context. PMs focus on product docs without understanding technical constraints.
• The maintenance problem remains: Keeping a dozen AI-generated documents synchronized is easier than manual updates, but still harder than maintaining one. When you learn something during development, you still face the choice of updating all documents, some documents, or none.
• The drift problem continues: Each document becomes a snapshot of thinking at different moments. The brief reflects initial understanding, the architecture doc shows the plan before implementation, and the detailed design captures assumptions that may have changed.

By the time you ship, you still have multiple documents telling different stories about different points in time. AI made them prettier and faster to create, but didn't make them more likely to stay current or get read.

The One Document Approach

Our solution is radical in its simplicity: one plan document that contains everything.

• The plan starts with the PM writing goals, problem description, user stories, and success metrics based on user research and market analysis.
• Engineering adds technical perspective by editing the same document to include architecture, key components, implementation approach, and technical considerations.
• Claude Code participates throughout by reading the plan to understand context, suggesting improvements, and updating it as code is written.
• Everyone works in the same file using Nimbalyst's markdown editor, iterating together rather than in isolated documents.

At the end of development, you have one document that accurately reflects both the original intent and the final implementation. It's a living source of truth that evolved with your understanding.

One Loop, One Document

Here's how the workflow actually works:

• PM Planning: I, as PM, write an initial plan document with Claude Code, iterating on it. The plan includes goals, problem description, user stories, acceptance criteria, and success metrics. All based on the user research and market research I've already done.
• Dev Planning: I hand that plan document to our developers. They iterate on it with me and Claude Code, adding technical architecture, implementation details, and engineering perspective. We're all editing the same markdown file.
• Claude Code Coding: Then developers hand the plan to Claude Code to use for coding. As Claude Code writes the implementation, it updates the plan document to reflect what was actually built.
• One loop. One document. From product vision through technical implementation to final code.

Why This Works Better Than Multi-Document Approaches

The Evolution From Pre-AI to AI to One-Doc

In the pre-AI era, comprehensive documentation was expensive to create and even more expensive to maintain. So teams often chose between:

• Over-documentation: Creating PRDs, technical specs, ERDs, architecture diagrams, and test plans that would immediately fall out of date. High upfront cost, low ongoing value.
• Under-documentation: Skipping formal planning entirely and relying on tribal knowledge. Low upfront cost, but constant confusion and miscommunication.

Neither approach worked well, but at least under-documentation saved time.

AI tools initially seemed to solve the cost problem. With BMAD, SpecKit, and similar frameworks, you could generate comprehensive multi-document specifications in hours instead of days. The upfront cost dropped dramatically.

But AI helps with but doesn't fully solve the organization problem (keeping track of all the documents) and the maintenance problem and it definitely doesn't solve the human reading problem. You still ended up with multiple documents that drifted apart as development progressed and that different team members read selectively.

The one-doc approach takes a different philosophy: what if we make documentation so lightweight and integrated that maintaining it becomes easier than letting it drift? What if we make it so focused that reading the whole thing is faster than cherry-picking sections from multiple documents?

We're lazy. We want simplicity. And we've found that one well-structured plan document beats both pre-AI multi-docs and AI-generated multi-docs every time.

What Goes in the One Plan Document?

Our plan documents include sections that traditionally lived in separate documents:

• Goals section outlining objectives and why we're building this.
• Problem description including Jobs to be Done, use cases, and user stories that provide product context.
• Requirements section with both high-level and specific functional requirements.
• High-level approach describing what we'll build without prescribing implementation details.
• Key components or phases showing how the solution breaks down architecturally.
• Technical considerations where engineering adds constraints, dependencies, and implementation notes.
• Acceptance criteria defining what "done" means.
• Success metrics and KPIs showing what success looks like measurably.
• Open questions capturing uncertainties that need resolution.

This covers everything traditionally split across PRD, technical design, architecture doc, and test plan. But it lives in one readable, maintainable markdown file with YAML frontmatter for status tracking.

How It Works With Design and Stakeholders

A common question: how do non-technical stakeholders engage with a technical plan document?

The answer is that the document isn't technical by default. It includes both product and technical perspectives in readable markdown.

Business stakeholders read the goals, problem description, and success metrics. They don't need to understand implementation details to follow the plan.

Design collaborates on user stories, acceptance criteria, and the high-level approach sections.

Engineering focuses on technical considerations, architecture, and components while maintaining awareness of product goals.

Because it's one document with clear sections, each stakeholder can engage with relevant parts without losing sight of the whole picture.

The plan lives in version control, so stakeholders can see changes over time and comment on specific sections through pull requests or direct edits.

Formatting for Both Humans and AI

We are formatting plans to be readable by both humans and AI, similar to how websites format content for both readers and search engines.

The structured markdown format with clear section headers helps humans scan and navigate. The YAML frontmatter provides metadata (status, priority, dates) that both people and Claude Code can query.

When Claude Code reads the plan, it understands the structure:

• Goals indicate intent
• Problem description provides context
• Requirements specify constraints
• Acceptance criteria define success

This structured format makes the plan a effective input for AI code generation. Claude Code doesn't just read the plan, it understands it and can reference specific sections when making implementation decisions.

The Human-in-the-Loop Reality

Some critics worry that AI-assisted planning bypasses proper product management. That's a misunderstanding of the workflow.

The plan document is entirely human-driven. As PM, I start the plan based on user research, market analysis, and strategic priorities I've established through traditional PM work.

Claude Code acts as a thought partner. It's particularly valuable because it can read our codebase, which helps me factor in technical reality while planning.

But the decisions are human. The research is human. The iteration is human. Claude Code assists in drafting, formatting, ensuring consistency, and eventually implementing, but humans drive the process at every stage.

The plan doesn't have "very little relevance the minute after it's been written" because it's continuously updated by the humans working on the feature. It's a living document, not a static specification.

Comparison: One Doc vs. Multi-Doc Approaches

This isn't to say BMAD and Spec Kit are wrong, or that pre-AI approaches had no value. They're sophisticated frameworks that work well for certain teams and contexts—particularly larger organizations that need detailed documentation for compliance, handoffs between teams, or formal review processes. Spec Kit's 5-document approach is notably more streamlined than BMAD's 10-20+ sharded files, showing that even within AI-assisted planning there's a spectrum of complexity.

But for teams that value simplicity, maintainability, and tight collaboration between product and engineering, one document solves problems that neither pre-AI documentation nor AI-generated multi-doc approaches fully address.

Getting Started With One-Doc Planning

If you want to try this approach:

• Create a plan template that includes both product and technical sections. Start with goals, problem description, requirements, approach, components, acceptance criteria, and success metrics.
• Add YAML frontmatter for status tracking. Include fields like status, priority, owner, dates, and progress percentage.
• Use Claude Code as a thought partner when drafting plans. Ask it to read your codebase and suggest approaches that align with existing architecture.
• Make the plan collaborative by having both PM and engineering edit the same file. Use version control to track changes and facilitate discussion.
• Keep it updated as you build. When implementation reveals new information or when you adjust approach, update the plan. Make it a living document, not a dusty artifact.
• Use it as input for development. Hand the plan to Claude Code when starting implementation. The plan becomes the context that guides code generation.

Why Simplicity Wins

The best process is one that people actually follow. Multi-document approaches create friction that leads to abandonment.

When updating documentation requires editing four files, finding the right sections, and ensuring consistency across all of them, people stop doing it. The documentation becomes outdated.

When reading documentation requires opening multiple files, understanding different formats, and reconciling conflicting information, people stop reading it. The documentation becomes ignored.

One plan document removes this friction. Updating is easy because there's one file. Reading is easy because there's one story. Staying in sync is easy because there's only one source of truth.

This simplicity enables the documentation to actually serve its purpose: providing shared understanding that stays current throughout development.

The Living Source of Truth

The most powerful aspect of one-doc planning is what you end up with at the end.

Pre-AI approaches left you with a PRD that reflected initial thinking (but was never updated), technical design docs that showed the plan before reality hit, ERDs that didn't match the final schema, and code that told the truth about implementation but not about intent. Six months later, new team members would ask "why did we build it this way?" and you'd say "I think there was a PRD somewhere, but honestly, just read the code and ask Sarah."

AI multi-doc approaches leave you with beautiful, polished documents that each tell a piece of the story at different points in time. The brief captures early thinking, the architecture doc shows the pre-implementation plan, and the detailed design reflects assumptions that changed during development. They're easier to create than pre-AI docs, but they still become historical artifacts rather than current truth.

With one living plan document, you finish development with a document that accurately describes:

• Why you built it (original goals)
• What you learned (updated problem understanding)
• How you built it (technical approach)
• What success looks like (metrics and acceptance criteria)
• What you actually shipped (implementation details)
• Why you made key decisions along the way

This becomes organizational memory. When someone asks six months later "why did we build it this way?", the plan document tells the complete story. Product intent and technical implementation live together in one readable narrative that stayed current throughout development.

This is what documentation should be: a living source of truth that actually reflects reality, not a collection of historical snapshots that diverged from each other weeks before shipping.

Key Takeaways

Pre-AI documentation failed because of maintenance and reading burden, not because it wasn't comprehensive enough. Creating more detailed documentation doesn't solve the fundamental problem that people won't read or maintain it.

AI makes documentation faster to create but doesn't solve the core problems. BMAD and Spec Kit are sophisticated multi-document approaches that generate better docs faster, but multiple documents still drift apart and don't get fully read.

Fewer documents means better documentation. One well-maintained plan beats four out-of-sync specifications, whether those specs were created manually or with AI assistance.

Collaboration improves when everyone works in the same file. PMs and engineers build shared understanding by editing together rather than in isolation across separate PRDs, technical design docs, and architecture diagrams.

AI assistance works better with complete context. Claude Code generates better code when it can read product goals and technical constraints in one place rather than jumping between fragmented documents.

Living documents beat static specifications. Plans that evolve during development stay relevant and accurate, while multi-document approaches—even AI-generated ones—become snapshots of thinking at different points in time.

Simplicity enables consistency. When updating is easy, people actually do it. When reading is easy, people actually understand. When there's one source of truth, it stays true.

Pre-AI multi-doc approaches were expensive to create and impossible to maintain. AI multi-doc approaches like BMAD and Spec Kit are faster to create but still hard to maintain and fully read. One-doc planning solves the problems that persisted across both eras: the documentation actually gets read, actually stays current, and actually serves as a shared source of truth throughout development.

Get Started

Ready to simplify your planning process? Start with your next feature. Create one plan document that brings together product vision and technical design. Invite both PM and engineering to edit it collaboratively. Use it as input for Claude Code when you start building. Watch how much easier it becomes to stay aligned and keep documentation current.

Need a UI and tool to help you?  Nimbalyst provides an integrated markdown environment: a markdown editor tied to Claude Code, a UI to manage Claude Code, and session management, with planning tools.  Try it here