The Crisis We Face
You've been there. It's 3 PM on a Friday. You're diving into a critical bug, but the original developer left six months ago. The code comments say "temporary fix" from 2019. The documentation is a README that says "TODO: add documentation." You spend the next five hours archaeologically excavating the codebase, piecing together context from scattered Slack messages and cryptic commit messages.
This is the reality of modern software development. And it's killing our productivity.
- 58% of engineering leaders report developers lose 5+ hours weekly to missing context.
- 80% of AI initiatives fail due to poor problem communication.
- 41% of developers cite insufficient documentation as their top time-waster.
The irony? We've never had more powerful tools. AI can write entire functions in seconds. But feed it vague requirements, and you'll get vague code. Worse, you'll get confident-looking wrong code.
Twenty years ago, the Agile Manifesto declared "working software over comprehensive documentation." It was the right call then. But the game has changed. Our new AI teammates need context to be effective. And frankly, so do we.
Context-Driven Development isn't about returning to waterfall documentation. It's about evolving beyond tribal knowledge.
Core Values
Context over code
Write the why, not just the what. Working software remains essential. But without clear problem statements and domain knowledge, even the best code becomes technical debt. We capture constraints, decisions, and rationale where they belong: next to the code itself.
Clarity over assumptions
Make the implicit explicit. Every assumption is a future bug. We demand precise language, reproducible steps, and explicit criteria. No more "it doesn't work" tickets. No more mind-reading required.
Shared knowledge over siloed expertise
Documentation is a team sport. When one person holds all the context, the entire team is one resignation away from crisis. We democratize knowledge, making it accessible to every developer and every AI tool.
Continuous refinement over perfect planning
Evolve context with your code. We don't write novels. We maintain living documents that grow with each sprint. Every PR updates both code and context. Every retrospective sharpens our shared understanding.
Principles
Foundation Principles
1. Context lives with code. Stop scattering knowledge across wikis, tickets, and chat. Embed specs, decisions, and constraints directly in your repository. One source of truth for humans and AI alike.
2. Write once, accelerate forever. Every minute documenting saves hours debugging. Clear specs prevent rework. Explicit constraints prevent scope creep. Context compounds like interest.
3. Make context debt visible. Track time lost to missing information. Measure onboarding friction. Monitor AI success rates. What gets measured gets fixed.
Communication Principles
4. Ban vague bug reports. No ticket enters the backlog without: clear title, environment, reproduction steps, expected vs actual behavior. Use templates. Enforce with automation. No exceptions.
5. Prompts are specifications. AI prompts aren't throwaway text. They're product requirements. Version control them. Review them. Refine them. Share what works.
6. Teach clarity as craft. Writing clear tickets isn't a soft skill—it's engineering. Train your team. Celebrate great documentation. Make heroes of context creators.
Evolution Principles
7. Context evolves with code. Every PR updates documentation. Every feature documents its decisions. Every deprecation explains its replacement. Living documents, not tombstones.
8. Automate context quality. Linters for documentation. CI checks for missing context. Templates for consistency. Make the right thing the easy thing.
9. Human judgment, AI acceleration. AI writes code, humans provide wisdom. AI suggests solutions, humans validate trade-offs. Partnership, not replacement.
These aren't suggestions. They're the new non-negotiables for teams that want to thrive in the AI era.
Join the Movement
The future of software development demands clarity. Will you lead the change, or be left behind?
For Developers
- Start writing context with your code
- Champion clear bug reports
- Share your AI prompts
- Measure your context debt
For Team Leads
- Implement CDD practices
- Track productivity gains
- Train your team
- Build context culture
For Organizations
- Transform your workflow
- Reduce AI project failures
- Scale knowledge sharing
- Future-proof your teams
Sign the manifesto. Share your story. Shape the future.
Already adopted by teams at Google, Microsoft, and hundreds of startups worldwide.
Context-Driven Development. Because the best code tells its own story.