A development methodology that treats natural language context as code. Instead of writing code first and documenting later, you start with clear specifications that both humans and AI agents can understand and execute.
Tell your AI agent:
Apply Codev to this repo following the instructions at https://github.com/ansari-project/codev/
Then say "I want to build X using the SPIDER protocol" or "Teach me about Codev".
Watch a brief overview of what Codev is and how it works.
Generated using NotebookLM - Visit the notebook to ask questions about Codev and learn more.
Join the conversation in GitHub Discussions! Share your specs, ask questions, and learn from the community.
Get notified of new discussions: Click the Watch button at the top of this repo → Custom → check Discussions.
A comprehensive walkthrough of the Codev methodology and its benefits.
See Codev in action! Follow along as we use the SPIDER protocol to build a conversational todo list manager from scratch:
This tour demonstrates:
- How to write specifications that capture all requirements
- How the planning phase breaks work into manageable chunks
- The IDE loop in action (Implement → Defend → Evaluate)
- Multi-agent consultation with GPT-5 and Gemini Pro
- How lessons learned improve future development
Codev is a development methodology that treats natural language context as code. Instead of writing code first and documenting later, you start with clear specifications that both humans and AI agents can understand and execute.
📖 Read the full story: Why We Created Codev: From Theory to Practice - Learn about our journey from theory to implementation and how we built a todo app without directly editing code.
- Context Drives Code - Context definitions flow from high-level specifications down to implementation details
- Human-AI Collaboration - Designed for seamless cooperation between developers and AI agents
- Evolving Methodology - The process itself evolves and improves with each project
Our flagship protocol for structured development:
- Specify - Define what to build in clear, unambiguous language
- Plan - Break specifications into executable phases
- For each phase: Implement → Defend → Evaluate
- Implement: Build the code to meet phase objectives
- Defend: Write comprehensive tests that protect your code—not just validation, but defensive fortifications against bugs and regressions
- Evaluate: Verify requirements are met, get user approval, then commit
- Review - Capture lessons and improve the methodology
your-project/
├── codev/
│ ├── protocols/
│ │ └── spider/ # The SP(IDE)R protocol
│ │ ├── protocol.md # Detailed protocol documentation
│ │ ├── manifest.yaml
│ │ └── templates/ # Document templates
│ ├── specs/ # Feature specifications
│ ├── plans/ # Implementation plans
│ ├── reviews/ # Review and lessons learned
│ └── resources/ # Reference materials (llms.txt, etc.)
├── AGENTS.md # AI agent instructions (AGENTS.md standard)
├── CLAUDE.md # AI agent instructions (Claude Code)
└── [your code]
- Specifications, plans, and lessons all tracked
- All decisions captured in version control
- Clear traceability from idea to implementation
- Structured formats that AI agents understand
- Multi-agent consultation support (GPT-5, Gemini Pro, etc.)
- Reduces back-and-forth from dozens of messages to 3-4 document reviews
- Supports both AGENTS.md standard (Cursor, Copilot, etc.) and CLAUDE.md (Claude Code)
- Every project improves the methodology
- Lessons learned feed back into the process
- Templates evolve based on real experience
Both projects below were given the exact same prompt to build a Todo Manager application using Claude Code with Opus. The difference? The methodology used:
- Built using a VIBE-style prompt approach
- Shows rapid prototyping with conversational AI interaction
- Demonstrates how a simple prompt can drive development
- Results in working code through chat-based iteration
- Built using the SPIDER protocol with full document-driven development
- Same requirements, but structured through formal specifications and plans
- Demonstrates all phases: Specify → Plan → (IDE Loop) → Review
- Complete with specs, plans, and review documents
- Multi-agent consultation throughout the process
Note: This comparison was generated through automated analysis by 3 independent AI agents (Claude, GPT-5, and Gemini Pro), not human review. The findings below represent their consensus assessment:
| Aspect | VIBE | SPIDER |
|---|---|---|
| Overall Score | 12-15 | 92-95 |
| Functionality | 0 | 100 |
| Test Coverage | 0 | 85 |
| Documentation | 0 | 95 |
| Architecture | N/A | 90 |
| Production Readiness | 0 | 85 |
VIBE Implementation:
- ❌ 3 files total - Just Next.js boilerplate
- ❌ 0% functionality - No todo features implemented
- ❌ 0 tests - No validation or quality assurance
- ❌ No database - No data persistence
- ❌ No API routes - No backend functionality
- ❌ No components - Just default Next.js template
SPIDER Implementation:
- ✅ 32 source files - Complete application structure
- ✅ 100% functionality - Full CRUD operations
- ✅ 5 test suites - API, components, database, MCP coverage
- ✅ SQLite + Drizzle ORM - Proper data persistence
- ✅ Complete API - RESTful endpoints for all operations
- ✅ Component architecture - TodoForm, TodoList, TodoItem, ConversationalInterface
- ✅ MCP integration - AI-ready with server wrapper
- ✅ Type safety - TypeScript + Zod validation
- ✅ Error handling - Boundaries and optimistic updates
- ✅ Documentation - Specs, plans, and lessons learned
As GPT-5 noted: "SPIDER's methodology clearly outperformed... Plan-first approach with defined scope, iterative verification, and delivery mindset"
Gemini Pro explained: "SPIDER correctly inferred the user's intent... It saves hours, if not days, of setup... It builds code the way a professional team would"
The verdict from all 3 agents: Context-driven development ensures completeness, while conversational approaches can miss the mark entirely despite identical prompts and AI models.
Codev is self-hosted - we use Codev methodology to build Codev itself. This means:
- Our test infrastructure is specified in
codev/specs/0001-test-infrastructure.md - Our development process follows the SP(IDE)R protocol we advocate
- Our improvements come from lessons learned using our own methodology
This self-hosting approach ensures:
- The methodology is battle-tested on real development
- We experience the same workflow we recommend to users
- Any pain points are felt by us first and fixed quickly
- The framework evolves based on actual usage, not theory
You can see this in practice:
- Check
codev/specs/for our feature specifications - Review
codev/plans/for how we break down work - Learn from
codev/reviews/to see what we've discovered
This repository has a dual nature:
-
codev/- Our instance of Codev for developing Codev itself- Contains our specs, plans, reviews, and resources
- Example:
codev/specs/0001-test-infrastructure.mddocuments how we built our test suite
-
codev-skeleton/- The template that gets installed in other projects- Contains protocol definitions, templates, and agents
- What users get when they install Codev
- Does NOT contain specs/plans/reviews (those are created by users)
In short: codev/ is how we use Codev, codev-skeleton/ is what we provide to others.
Our comprehensive test suite (64 tests) validates the Codev installation process:
- Framework: Shell-based testing with bats-core (zero dependencies)
- Coverage: SPIDER protocol, SPIDER-SOLO variant, CLAUDE.md preservation, agent installation
- Isolation: XDG sandboxing ensures tests never touch real user directories
- CI/CD Ready: Tests run in seconds with clear TAP output
- Multi-Platform: Works on macOS and Linux without modification
- Pre-commit Hook: Automatically runs tests before commits
Run tests locally:
# Fast tests (< 30 seconds)
./scripts/run-tests.sh
# All tests including Claude CLI integration
./scripts/run-all-tests.shInstall pre-commit hook for development:
# Install git hooks (runs tests before each commit)
./scripts/install-hooks.shSee tests/README.md for detailed test documentation.
Ask your AI agent to:
Install Codev by following the instructions at https://github.com/ansari-project/codev/blob/main/INSTALL.md
The agent will:
- Check for prerequisites (Zen MCP server)
- Create the codev/ directory structure
- Install the appropriate protocol (SPIDER or SPIDER-SOLO)
- Set up or update your CLAUDE.md file
See examples/todo-manager/ for a complete walkthrough showing:
- How specifications capture all requirements
- How plans break work into phases
- How the IDE loop ensures quality
- How lessons improve future development
Templates in codev/protocols/spider/templates/ can be modified to fit your team's needs:
spec.md- Specification structureplan.md- Planning formatlessons.md- Retrospective template
Codev includes three specialized AI agents to enhance your development workflow (requires Claude Code with the Task tool):
Keep your Codev installation up-to-date with the latest protocols and improvements:
# Update your Codev framework
"Please update my codev framework to the latest version"The agent will:
- Check for updates to protocols (SPIDER, TICK, etc.)
- Update agents and templates
- Preserve your specs, plans, and reviews
- Create backups before updating
- Provide rollback instructions
Automatically maintains comprehensive architecture documentation:
# Invoked automatically at the end of TICK protocol reviews
# Or manually: "Update the architecture documentation"The agent maintains codev/resources/arch.md with:
- Complete directory structure
- All utility functions and helpers
- Key architectural patterns
- Component relationships
- Technology stack details
Learn from SPIDER implementations across the community:
# Check a repository for SPIDER improvements
"Check [repository-url] for SPIDER improvements"The agent will:
- Analyze the repository's SPIDER implementation
- Compare against current protocol
- Identify improvements and lessons learned
- Suggest protocol updates with justification
Example repositories to monitor:
ansari-project/todo-manager-spider- SPIDER implementation with lessons- Your own SPIDER projects with discovered patterns
We welcome contributions! Please help us improve Codev:
- Bug Reports: Open an issue with clear reproduction steps
- Feature Requests: Share your ideas for new features or improvements
- Documentation: Report unclear or missing documentation
- Questions: Ask for clarification or help with implementation
- New protocols beyond SP(IDE)R
- Improved templates
- Integration tools
- Case studies
- SPIDER protocol improvements from your implementations
MIT - See LICENSE file for details
Built with Codev - where context drives code