autonomous-dev

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 --install or brew 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.