document-driven-development

Synchronizes documentation, code, and tests through a documentation-first engineering workflow.

Updated Sep 10, 2026
One-click install
npx skills add https://github.com/lunarmoon26/agent-skills --skill document-driven-development-lunarmoon26
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: document-driven-development
Source: https://github.com/lunarmoon26/agent-skills/tree/main/skills/document-driven-development
Command: npx skills add https://github.com/lunarmoon26/agent-skills --skill document-driven-development-lunarmoon26

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Teams often let documentation drift out of sync with code and tests, leaving specs stale, contracts ambiguous, and shipped behavior undocumented. This Skill enforces a documentation-first change loop where accepted behavior is written down, implemented, verified, and reconciled in the same change. ## Core Features & Use Cases - Authority mapping by fact type: Assigns each fact to a single canonical owner, such as schemas for exact shapes, focused specs for behavior, and ADRs for rationale. - Bounded change loop: Guides inspection, delta documentation, minimal implementation, contract verification, and drift reconciliation with a closure receipt. - Drift resolution: Provides a structured process for handling disagreements between docs, code, tests, and machine artifacts without defaulting to the newest prose. - Use Case: When adding idempotency keys to an existing payments API, use this Skill to update the OpenAPI schema and API guide first, implement against the documented contract, map tests to acceptance criteria, and close the loop without creating a generic PLAN.md. ## Quick Start Use document-driven development to add a bounded feature contract for this change, then implement and verify it against the documented acceptance criteria.

Frequently Asked Questions about document-driven-development

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I practice document-driven development on an existing codebase?▼

Document-driven development starts by inspecting existing docs, schemas, and tests to find the canonical owner of each fact. Write the behavior delta and acceptance criteria in that owner first, then implement minimally, verify against the contract, and reconcile any discoveries in the same change.

What is the difference between document-driven development and spec-driven development?▼

Document-driven development treats documentation as part of engineering, keeping one canonical owner per fact and reconciling drift continuously. The Markdown-as-executable-source variant of spec-driven development is an opt-in experimental pattern, not a default requirement of this workflow.

When should I not use document-driven development?▼

Skip the full workflow for tiny, local, reversible changes with no contract impact, such as fixing a README typo. It is also not intended for architecture briefs, ADRs alone, or comparative source research, which belong to other workflows.

How do I fix documentation that disagrees with the code?▼

Treat the disagreement as drift: name the conflicting claims, identify each fact's canonical owner, and determine intended behavior from evidence rather than preferring the newest prose or current code. Reconcile the owning artifacts in one scoped change and delete stale derived text.

Does document-driven development require creating PLAN.md or ARCHITECTURE.md files?▼

No, the workflow explicitly avoids pre-creating standard document sets before inspecting the repository. Bootstrap only documents that already have real content, starting with a README and adding focused specs or decision records only when genuine need appears.