AI-Driven Development

A quality methodology for AI-assisted software development. Six layers, adopted incrementally, each addressing a gap the previous layer cannot fill.

This is not a framework or a library. It is a way of working -- a set of practices that help developers and AI agents build, verify, and evolve software together.

Early development. The methodology specification is complete for its initial scope. Tooling, automation, and real-world validation are still in progress. See the Roadmap and Open Problems.

Who This Is For

• Solo developers using AI who can't keep up with their own system's complexity.
• Small teams where AI-generated code volume exceeds human review bandwidth.
• Any team where "tests pass" has become a form of false confidence.

The Layers

Layer	What	Gap it fills
0	Code	The foundation
1	Observability	"I can't see what happens inside"
2	Documentation	"Nobody knows the philosophy"
3	AI Instructions	"AI doesn't follow conventions even with docs"
4	Callable Surface	"Nobody verifies the system works e2e"
5	Journey Verification	"Nobody checks quality from the user's perspective"

Each layer is earned by the failure of the previous one. Adopt them in order.

Quick Start

1. Read The Problem to understand why.
2. Read Principles for the design philosophy.
3. Read Layer by Layer for the full narrative.
4. Read Adoption Guide to start adopting.

Documentation

Foundation

• The Problem -- Why existing practices fail when AI accelerates delivery.
• Principles -- Design principles for documentation, instructions, and verification.

Layers

• Layer by Layer -- The six layers, told as a day-by-day evolution.
• Observability -- What to observe, when, and what constitutes a finding.

Journeys

• Journey Design -- What a journey is, how to write one.
• Walk Procedure -- Pre-walk, walk, report, fix, re-walk.
• Evaluation Criteria -- Scoped, binary criteria that replace subjective scoring.
• Black Box vs White Box -- Two evaluation modes with different context boundaries.

Context

• Comparison -- How this relates to TDD, BDD, SDD, vibe coding, and adjacent approaches.
• Open Problems -- Known gaps and future directions.

Reference

• Glossary
• Roadmap
• Adoption Guide
• Samples -- Copy-and-adapt instructions, skills, hooks, journeys.

Plugin

Cross-tool plugin with skills and agents for AI-assisted verification.

Skills

• walk-journey -- Walk a journey against a callable surface
• evaluate-criteria -- Evaluate walk results against binary criteria
• design-journey -- Design new journeys with proper structure
• analyze-trace -- Analyze distributed traces for quality metrics

Agent

• journey-walker -- Specialized verification agent that walks journeys

Install

VS Code / Copilot: Run Chat: Install Plugin From Source and enter:

https://github.com/GiviKDev/ai-driven-development

Claude Code:

/plugin install ai-driven-development

Repository Structure

docs/           Methodology specification (numbered)
plugin/         Cross-tool plugin (skills, agents)
samples/        Copy-and-adapt samples
specs/          Tooling specifications
.github/        CI/CD, templates, instructions

Contributing

See CONTRIBUTING.md for guidelines. This project follows the Contributor Covenant code of conduct.

Local Setup

git clone https://github.com/GiviKDev/ai-driven-development.git
cd ai-driven-development
make setup

Blog

Read the concise overview at givikdev.github.io/ai-driven-development.

License

CC BY 4.0 -- share, adapt, attribute.