autonomous-dev
Traditional software engineering meets AI.
Claude is brilliant but drifts. It starts with a plan, then improvises. Documentation falls out of sync. Tests get "added later." Direction shifts mid-feature.
autonomous-dev provides macro alignment with micro flexibility:
- Macro: PROJECT.md defines goals, scope, constraints — Claude checks alignment before every feature
- Micro: Claude can still improve the implementation when it finds better patterns
research → plan → test → implement → review → security → docs → commit
Every step. Every feature. Documentation, tests, and code stay in sync automatically.
/auto-implement "issue #72"
Quick Start (macOS)
# 1. Install
bash <(curl -sSL https://raw.githubusercontent.com/akaszubski/autonomous-dev/master/install.sh)
# 2. Restart Claude Code (required - commands are cached)
# Press Cmd+Q, then reopen
# 3. Use
/auto-implement "your feature description"
Requirements:
- Claude Code 2.0+
- macOS (not tested on Windows/Linux)
- Python 3.9+
System tools (install separately):
- git:
xcode-select --installorbrew install git - gh CLI:
brew install gh && gh auth login(required for GitHub automation)
For contributors: Development dependencies are in plugins/autonomous-dev/requirements-dev.txt (pytest, coverage, etc.)
The Problem We Solve
Claude working alone drifts. Claude working within a framework stays consistent.
| Without autonomous-dev | With autonomous-dev |
|---|---|
| Claude decides workflow per-session | Same 8-step pipeline every time |
| Plan drifts mid-implementation | Macro alignment checked, micro improvements allowed |
| Tests written "if time permits" | Tests written first (TDD enforced) |
| Documentation falls out of sync | Auto-updated every feature |
| "Best practices" from training data | Actual web search with source URLs |
| Scope creep ("while I'm here...") | Out-of-scope requests blocked |
| Manual commit/push/PR | Automated git workflow |
The insight: This isn't about limiting Claude. It's about fusing traditional software engineering discipline with AI capability. Claude brings intelligence; the framework brings consistency.
What Actually Happens
When you run /auto-implement "add user authentication":
| Step | What Happens | Time |
|---|---|---|
| 0. Alignment | Checks feature against PROJECT.md scope | <1 min |
| 1. Research | Searches codebase AND web (parallel) | 2-3 min |
| 1.1 Validation | Verifies web search actually ran (not hallucinated) | <1 min |
| 2. Planning | Designs implementation approach | 2-4 min |
| 3. TDD Tests | Writes failing tests first | 3-8 min |
| 4. Implementation | Makes tests pass | 3-8 min |
| 5-7. Validation | Review + Security + Docs (parallel) | 2-4 min |
| 8. Git | Commit, push, PR (automated) | <1 min |
Total: 15-30 minutes depending on complexity.
After completion:
- ✅ Code committed with conventional commit message
- ✅ Changes pushed to your branch
- ✅ Pull request created
- ✅ GitHub issue auto-closed
Why Web Research Matters
Most AI coding tools answer from training data. That's fine for "how do I sort a list" but dangerous for "what's the current best practice for JWT authentication."
We force actual web search:
└─ Task (Research best practices) · 5 tool uses ✅
⎿ Web Search: JWT authentication best practices 2024...
If you see 0 tool uses, the pipeline blocks:
❌ Web research failed: 0 WebSearch calls made.
Results would be hallucinated. Retrying...
This validation was added because we caught Claude returning "best practices" that it never actually searched for.
PROJECT.md: Your Scope Boundary
# .claude/PROJECT.md
## GOALS
- Build REST API for user management
- Ship MVP by end of Q1
## SCOPE
IN: User CRUD, authentication, password reset
OUT: Admin dashboard, analytics, billing
## CONSTRAINTS
- Python 3.11+ with FastAPI
- PostgreSQL database
- JWT authentication (no sessions)
Request something IN scope: Claude follows your constraints.
Request something OUT of scope: Blocked immediately.
❌ BLOCKED: Feature not aligned with PROJECT.md
Feature requested: "Add analytics dashboard"
Why blocked: Explicitly OUT of scope
This prevents the "while I'm here, let me also refactor..." drift.
Honest Benchmarks
We document typical performance, not marketing claims.