We have open-sourced a methodology and toolchain called IDD (Intent Driven Development). Its core philosophy, in a single sentence, is:"Tell AI *the intent*, not *what to do*."
With AI-assisted programming becoming the norm, traditional requirement documents, user stories, and technical specifications increasingly feel outdated. These were originally designed for human collaboration, but when applied to human-machine scenarios, AI often misinterprets even extensive documentation, resulting in endless rounds of revisions. The IDD approach proposes a paradigm shift: rather than instructing AI on *how* to do something, we should articulate *what* is needed, empowering AI to plan its own implementation. This article will delve into our rationale behind this approach and how this system functions in practice.
SDD vs IDD#
Software engineering has seen numerous attempts to address the challenge of "thinking clearly before acting." Spec Driven Development (SDD) stands as one such approach, whose fundamental principle involves meticulously crafting detailed specifications before proceeding with code implementation. While seemingly logical, this methodology has revealed its limitations in the age of AI.
Method | Process | Problem |
|---|---|---|
Traditional | Code → Test → Docs | Documentation is often outdated or missing |
SDD | Spec → Code → Test | Specs readily become obsolete and are spread across numerous files. |
TDD | Test → Code → Docs | Testing cannot convey design intent. |
DID | Intent → Test → Code → Sync | Intent defines 'what' and 'why,' while AI is responsible for 'how to do it.' |
I've had firsthand experience with the formalism inherent in SDD. Many years ago, while working at a major software company in Seattle, a PM on our team would transform any item into an exceedingly long, formulaic document. Matters easily explained in a few sentences were invariably split into over a dozen user stories. The documentation was pristine and seemingly watertight, yet after reviewing, one was still left unsure of its actual objective. Last year, while test-driving Amazon's Kiro, that familiar sensation resurfaced. Kiro is a quintessential SDD tool; it generates numerous spec files with a highly standardized structure. However, the pervasive sense of 'writing for writing's sake' was unmistakable. This isn't a problem with the tool itself, but with the underlying mindset – a direct transposition of traditional software engineering methodologies into the AI era. While the tools have evolved, the cognitive approach remains unchanged.
The fundamental issue with SDD lies in its continued adherence to traditional information organization: segregating data by requirement type (functional, UX, and technical requirements), breaking it down into user stories, and maintaining distinct task files. While this categorization is logical for human collaboration—allowing product managers to focus on functional requirements, designers on UX needs, and architects on technical specifications—it inadvertently fragments the complete context for AI. AI necessitates a holistic grasp of a module's full scope, rather than laboriously piecing together information from numerous disparate files. The more granular the traditional breakdown, the greater the computational effort AI must expend on reassembly, and any errors in this process inevitably lead to repeated corrective iterations.
IDD takes a different approach: it organizes by modules rather than demand types, preserving complete context. It eliminates the need for task files, empowering AI to autonomously decompose tasks. The Intent layer achieves a higher level of abstraction, describing "what effect is desired" instead of "how to implement it." Compared to TDD, IDD integrates an Intent layer before the testing phase. In contrast to SDD, IDD refrains from specifying implementation details, thereby affording AI the freedom to plan more effective solutions.
Why IDD Is Feasible#
You might ask: Without detailed specifications, how does AI know exactly what to do? Here's a counter-intuitive fact:In many fields, AI understands "how to do it" better than humans.
A while ago, I embarked on building a 6502 CPU Emulator. Traditionally, such an undertaking is considered "hardcore," demanding a deep grasp of CPU architecture, register design, and instruction encoding and decoding, with merely the design phase requiring extensive consultation of technical manuals. Opting for a traditional Software Design Document (SDD) approach would necessitate first drafting dozens of pages to meticulously detail every instruction and addressing mode. Yet, before the specification could even be finalized, the entire project would likely falter. Instead, I simply prompted the AI: "I require a 6502 Emulator capable of accurately executing its standard instruction set and possessing basic debugging functionalities." That was the extent of my instructions.
The outcome revealed a significant insight: the 6502, a chip introduced in 1975 that famously powered the Apple II and NES consoles, is surrounded by an incalculable volume of technical documentation and open-source implementations. Consequently, LLMs have processed far more emulator code than any human expert. The AI's proposed module division proved clearer than my own design, and the entire implementation, guided by Test-Driven Development (TDD) principles, was completed without a hitch. Tasks once considered the exclusive domain of the most senior engineers thus became remarkably simple for the AI, largely because such classic problems are exhaustively represented in its training data.
This forms the basis for IDD's viability: In domains adequately covered by AI training data, there's no need to instruct it on how to proceed; one merely needs to articulate what is desired. Given that AI has encountered far more patterns than humans, the solutions it devises are likely to be more rational than those we might conceive. Humanity's true value lies in discerning what it is right to want—this is the sphere that genuinely necessitates human intellect.
Intent is the New Source Code#
This sentence means:Code review can be delegated to AI, but intent review requires human oversight.
AI is proficient at verifying code for compliance with specifications, identifying security vulnerabilities, and ensuring adherence to project style. However, AI cannot determine 'if this feature is truly what we want'—a judgment only humans can make. Consequently, human effort should be concentrated on reviewing the Intent, rather than undertaking a line-by-line review of AI-generated code.
The Difference Between Intent and Traditional Requirements Documents:
Conventional Requirements | IDD Intent |
|---|---|
By Type (Function/Technology/UX) | By Module |
Describe "what it does" | Describe 'What Is Desired' |
Human-readable | Written for AI + Humans |
Once written, it rapidly becomes obsolete. | Stay in sync with the code |
Intent operates at a higher level of abstraction. There is no need to specify the technologies or architectural layers to the AI; it handles such planning autonomously. Your role is to clearly define: the desired outcome, any applicable constraints, and how boundary conditions should be managed.
Intent File Structure#
DID Intent files employ a three-layer structure:
1. Structure Diagram - ASCII diagrams illustrate module relationships and data flow. Diagrams offer greater precision than text, allowing LLMs to "understand" them directly.
2. Constraint Rules - Mandatory constraints, such as dependency direction and boundary rules. These can be directly converted into lint rules or test assertions.
3. Behavioral Examples - Specific inputs and outputs, including edge cases. Can be directly converted into test cases.
Design Principle:Every layer must be verifiable. Not vague descriptions, but constraints verifiable through code.
Toolchain#
We developed a set of Claude Code plugins:
Command | Features |
|---|---|
| Assessing Project Suitability for DID |
| Initialize the IDD directory structure |
| Turning interview insights into INTENT.md |
| Key Section for Intent Approval |
| Verify the code's consistency with the Intent. |
| Generate documentation from Intent |
The Complete Process:
/intent-assess # 评估是否适合
↓
/intent-init # 初始化结构
↓
/intent-interview # 创建 Intent
↓
/intent-review # 审批关键部分
↓
[AI 实现代码]
↓
/intent-check # 验证一致性
Installation:
npx add-skill arcblock/idd
Applicable Scenarios#
Suitable for IDD:
- AI-assisted development is the primary working method
- System software, frameworks, infrastructure
- Projects requiring strict architectural boundaries
May not be suitable for:
- Highly regulated industries must use traditional document formats
- The team has no AI tools
- User stories should be presented to non-technical personnel.
Final Thoughts#
Revisiting our opening question: What exactly should humans tell an AI? I believe the answer lies in articulating "what" is needed, rather than micromanaging "how" it should be done. In the age of AI, a spec-driven approach risks devolving into formalism; despite extensive documentation, the AI often fails to grasp the true intent. IDD, however, shifts this paradigm. Rather than meticulously prescribing the "how," it prioritizes clearly defining "what" is required, empowering the AI to devise its own implementation plan.
After a period of internal use, we are confident in the direction of this system. We are therefore open-sourcing it, anticipating it will also be of benefit to other teams.
GitHub: github.com/ArcBlock/idd