Vision-Driven Development — A framework for AI-autonomous software development with enforced safety boundaries.
"Don't just document rules — enforce them technically."
VDD Framework provides a complete methodology and tooling for AI-autonomous development, built around two core ideas:
- Vision-Driven Development (VDD): Keep your project aligned with its vision through structured decision-making, daily scoring, and debate-driven validation
- Release-Driven Development (RDD): Ship value in small, safe, rollback-friendly releases where AI handles implementation, testing, and review autonomously
The framework enforces safety through git worktree isolation, hook-based guardrails, and a clear authority matrix between humans and AI.
Human decides WHAT and WHY → AI decides HOW and executes
(Vision + QA) (Implementation + Review)
High autonomy and well-defined boundaries are two sides of the same coin.
The conventional approach to AI safety is a whitelist — telling the AI exactly what it can do, step by step. This framework takes the opposite approach: define what is forbidden, and everything else is permitted. By explicitly specifying the small set of actions that must never happen (force-push to main, editing files outside a worktree, merging without review), the AI gains maximum freedom to make its own decisions within those boundaries.
This works because the boundaries are technically enforced, not just documented. When an AI agent knows that a hook will physically block a dangerous operation, it doesn't need to second-guess every action — it can act decisively, knowing the guardrails will catch genuine mistakes. The branch strategy reinforces this: release/* branches in isolated worktrees give the AI a sandbox where it can work with full autonomy, while main and develop remain protected by structural rules.
The result: the clearer the boundaries, the more autonomous the agent becomes. Not despite the constraints, but because of them.
graph TB
subgraph VDD ["VDD (Strategy)"]
V[VISION.md] --> D[DECISIONS.md]
D --> DS[DAILY_SCORE.md]
end
subgraph RDD ["RDD (Execution)"]
P0[Phase 0: Requirements] --> P1[Phase 1: Design Dialogue]
P1 --> P2[Phase 2: Autonomous Implementation]
P2 --> P3[Phase 3: Self-Review + Independent Review]
P3 --> P4[Phase 4: Merge + QA]
end
subgraph Safety ["Safety Layer"]
H1[worktree-guard L5]
H2[commit-guard L5]
H3[review-enforcement L4]
H4[subagent-rules L3]
end
VDD -->|"Strategic Alignment"| RDD
Safety -->|"Enforce Boundaries"| RDD
# 1. Clone the framework
git clone https://github.com/shuhei0866/vdd-framework.git
# 2. Navigate to your project
cd your-project
# 3. Run the setup wizard
bash path/to/vdd-framework/scripts/init.shThe wizard will:
- Detect your project type (Node.js, Python, Rust, Go)
- Ask you to choose an adoption level (L1-L5)
- Copy and configure the appropriate files
- Set up git hooks and Claude Code integration
Start small, grow incrementally. Each level builds on the previous one.
| Level | Name | What You Get | Value |
|---|---|---|---|
| L1 | Safe Development | worktree-guard + commit-guard + git-worktrees skill | AI won't destroy uncommitted work |
| L2 | Structured Releases | L1 + RDD workflow + release specs + conversation logger | Structured release process |
| L3 | Quality-Enforced | L2 + agents + TDD + skills + review enforcement | AI autonomously implements, tests, and reviews |
| L4 | Vision-Aligned | L3 + VDD artifacts + decision authority matrix | Vision-driven strategic development |
| L5 | Full Autonomous | L4 + cloud execution + debate partner + multi-AI review | Fully autonomous pipeline |
Recommendation: Start with L1 to experience the safety model, then progress to L3 when ready for autonomous AI development.
Rules aren't just documented — they're technically enforced at four levels:
| Level | Label | Mechanism | Bypassable? |
|---|---|---|---|
| L5 | Hook Enforced (deny) | Hook blocks the action | No |
| L4 | Hook Warning (ask/block) | Hook requires confirmation | With user approval |
| L3 | Context Injection | Auto-injected into agent context | Agent sees it, but no hard block |
| L2 | Prompt-only Rule | Written in CLAUDE.md only | Yes (no enforcement) |
A simplified GitFlow with three layers:
main (production) ← Human promotes (release feedback meeting)
↑
develop (integration) ← AI merges after independent review approval
↑
release/* (work) ← AI implements in isolated git worktrees
- Git worktree isolation — All code changes happen in worktrees, never in the main working tree
- Commit guards — Blocks force-push to main, --no-verify, and other dangerous operations
- PR guards — Prevents unauthorized PR operations in cloud environments
- TDD-first — Test before implementation, enforced via context injection
- Self-review pipeline — AI runs quality checks, self-evaluation, and independent code review
- Multi-AI review — Different AI perspectives for comprehensive review (e.g., Claude + Codex)
- Subagent orchestration — Parallel implementation with task decomposition
- VISION.md — Living document defining project direction and values
- DECISIONS.md — Decision ledger with context and rationale
- DAILY_SCORE.md — Subjective daily score tracking development satisfaction
- Debate partner — External AI validates vision alignment before implementation
- code-reviewer — Independent code review with accumulated project knowledge
- implementer — TDD-driven implementation specialist
- release-manager — Release creation and versioning
| Skill | Purpose |
|---|---|
git-worktrees |
Create and manage isolated worktrees |
tdd |
Parallel TDD execution with subagents |
review-now |
Independent code review on local changes |
review-pr |
PR code review with GitHub comment posting |
release-ready |
Pre-release self-evaluation checklist |
release |
GitHub release creation from commit history |
task-decompose |
Break large tasks into parallel subtasks |
dig |
Structured requirement clarification |
security-balance |
4-axis security trade-off evaluation |
env-secrets |
Safe handling of environment variables and secrets |
Detailed documentation is available in both English and Japanese:
-
English: docs/en/
- Philosophy — Core beliefs and design principles
- VDD Specification — Vision-Driven Development
- RDD Specification — Release-Driven Development
- Getting Started — Step-by-step guide
- Adoption Levels — Incremental adoption path
- More...
-
Japanese / 日本語: docs/ja/
See reference implementations in examples/:
- minimal — Minimal Level 1 setup (just safety guardrails)
For a full-featured example, explore template/ which contains all hooks, agents, skills, and VDD artifacts for levels L1-L5.
- git 2.20+ (for worktree support)
- Claude Code CLI
- jq (for hook scripts)
- gh CLI (for GitHub integration, L2+)
See CONTRIBUTING.md for guidelines.
Built with the belief that AI should have maximum autonomy within enforced boundaries.