The standard framework for AI Driven Development
AI agents like Claude Code ship features fast. aidd Framework keeps them working, secure, and maintainable.
AI agents generate code that runs but fails at scale. GitClear tracked 211 million lines from 2020 to 2024 and found 8x more code duplication as AI adoption increased. Google's DORA report shows AI adoption correlates with 9% higher bug rates and degraded stability. Agents skip tests, couple modules, duplicate logic, and miss vulnerabilities.
AIDD provides the architecture, test workflows, and specification system that turn AI speed into sustainable velocity so you can ship secure, production-ready, maintainable software, quickly.
Includes:
AI-Driven Development (AIDD) is a methodology where AI systems take primary responsibility for generating, testing, and documenting code, automating most of the software creation process so humans can focus on the big picture and 10× their productivity.
AIDD Framework is a collection of reusable metaprograms, agent orchestration systems, and prompt modules that put high-quality software engineering processes on autopilot rails. It implements time-tested workflows including specification-driven development, systematic task planning with Test Driven Development (TDD), and automated code review with best practices enforcement.
SudoLang is a pseudocode language for prompting large language models with clear structure, strong typing, and explicit control flow.
AI Workflow Commands - Use these in your AI assistant chat (Cursor, ChatGPT, Claude, etc.):
/discover - what to build
/task - plan a task epic to implement a user story from the discovery
/execute - task epics with TDD
/review - the results
/log - log the changes to the activity log
/commit - commit the changes to the repository
/user-test - generate user testing scripts for post-deploy validation
npx aidd --help
To install for Cursor:
# In your project folder
npx aidd --cursor
Install without Cursor integration:
# You can also specify a project folder:
npx aidd my-project
Install SudoLang syntax highlighting: Visit the SudoLang Github Repository and install syntax highlighting for your editor.
Clone the AI system:
# Recommended: Creates ai/ folder + .cursor symlink for automatic integration
npx aidd --cursor my-project
# Alternative: Just the ai/ folder (manual integration required)
npx aidd my-project
Create a Vision Document (important!):
Create a vision.md file in your project root. This document serves as the source of truth for AI agents. See Vision Document for details.
Explore the structure:
cd my-project
ls ai/ # See available components
cat ai/rules/please.mdc # Read the main orchestrator
Start using AI workflows:
ai/rules/ in AI prompts for better contextai/commands/ as workflow templatesThis gives you immediate access to:
ai/rules/)ai/commands/)For features or bug fixes spanning more than a few lines:
git checkout -b your-branch-name/discover: Set up your project profile and discover key user journeys to create a user story map (saved to plan/story-map/)/task: Create a structured epic with clear requirements/review: Eliminate duplication, simplify without losing requirements/execute: Implement using TDD, one requirement at a timegit push origin your-branch-name then open a Pull RequestNote: We use this process to build the aidd framework. See CONTRIBUTING.md for details.
Validate features with real users and AI agents. AIDD generates dual testing scripts from user journeys:
Research from the Nielsen Norman Group shows that testing with just 3-5 users reveals 65-85% of usability problems. Iterate quickly by testing small, fixing issues, and testing again.
Quick start:
/discover # Create user journey (saved to plan/story-map/)
/user-test journey.yaml # Generate testing scripts (saved to plan/)
/run-test agent-script # Execute AI agent test
📖 Read the complete User Testing Guide →
For most simple prompts, natural language is better. Use it. But if you need the AI to follow a program, obey constraints, keep track of complex state, or implement complex algorithms, SudoLang can be extremely useful.
Please read the SudoLang documentation for more information about the language.
Modules include:
Coming soon:
aidd Framework combines modern software engineering practices with AI orchestration. To use it effectively, you'll benefit from understanding:
📖 Complete Learning Roadmap → — Detailed competency areas, technical skills, and weekly training sessions
New to AI-driven development? Start with the Quick Start below, then explore the /discover → /task → /execute workflow. The AI agents will guide you through the process.
A lightweight alternative to Express, built for function composition and type-safe development.
Why AIDD Server?
Quick Example:
import {
createRoute,
withRequestId,
createWithConfig,
loadConfigFromEnv,
} from "aidd/server";
// Load API keys from environment with fail-fast validation
const withConfig = createWithConfig(() =>
loadConfigFromEnv(["OPENAI_API_KEY", "DATABASE_URL"])
);
export default createRoute(
withRequestId,
withConfig,
async ({ request, response }) => {
// Throws immediately if OPENAI_API_KEY is missing
const apiKey = response.locals.config.get("OPENAI_API_KEY");
response.status(200).json({
message: "Config loaded securely",
requestId: response.locals.requestId,
});
}
);
Core Features:
createRoute - Compose middleware with automatic error handlingcreateWithConfig - Fail-fast configuration with config.get()withRequestId - CUID2 request tracking for loggingcreateWithCors - Explicit origin validation (secure by default)withServerError - Standardized error responsescreateWithAuth / createWithOptionalAuth - Session validation with better-authAIDD Server includes optional auth middleware that wraps better-auth for session validation.
1. Install better-auth:
npm install better-auth
2. Configure better-auth (see better-auth docs):
// lib/auth.server.js
import { betterAuth } from "better-auth";
export const auth = betterAuth({
database: yourDatabaseAdapter,
emailAndPassword: { enabled: true },
});
3. Create auth API route (framework-specific):
// Next.js: app/api/auth/[...all]/route.js
import { toNextJsHandler } from "better-auth/next-js";
import { auth } from "@/lib/auth.server";
export const { GET, POST } = toNextJsHandler(auth);
4. Use AIDD auth middleware in protected routes:
import { createRoute, withRequestId, createWithAuth } from "aidd/server";
import { auth } from "@/lib/auth.server";
const withAuth = createWithAuth({ auth });
// Protected route - returns 401 if not authenticated
export default createRoute(withRequestId, withAuth, async ({ response }) => {
const { user } = response.locals.auth;
response.json({ email: user.email });
});
Optional auth for public routes that benefit from user context:
import { createWithOptionalAuth } from "aidd/server";
const withOptionalAuth = createWithOptionalAuth({ auth });
// Public route - user attached if logged in, null otherwise
export default createRoute(withOptionalAuth, async ({ response }) => {
const user = response.locals.auth?.user;
response.json({
greeting: user ? `Hello, ${user.name}` : "Hello, guest",
});
});
Passkey authentication (passwordless):
npm install @better-auth/passkey
// lib/auth.server.js
import { betterAuth } from "better-auth";
import { passkey } from "@better-auth/passkey";
export const auth = betterAuth({
database: yourDatabaseAdapter,
plugins: [passkey()],
});
// API route: Register passkey (requires authentication)
import { createRoute, createWithAuth } from "aidd/server";
import { auth } from "@/lib/auth.server";
const withAuth = createWithAuth({ auth });
export default createRoute(withAuth, async ({ request, response }) => {
const { user } = response.locals.auth;
// User is authenticated, register their passkey
const result = await auth.api.addPasskey({
body: { name: `${user.email}'s passkey` },
headers: request.headers,
});
response.json(result);
});
// API route: List user's passkeys
export default createRoute(withAuth, async ({ request, response }) => {
const passkeys = await auth.api.listPasskeys({
headers: request.headers,
});
response.json({ passkeys });
});
📖 See complete Server Framework documentation →
The AI Driven Development (AIDD) CLI tool clones the complete AI agent orchestration system to any directory.
# Recommended: Use npx (no installation required)
npx aidd [target-directory] [options]
# Alternative: Global installation
npm install -g aidd
aidd [target-directory] [options]
| Option | Description |
|---|---|
target-directory | Directory to create ai/ folder in (defaults to current) |
-f, --force | Overwrite existing ai/ folder |
-d, --dry-run | Show what would be copied without copying |
-v, --verbose | Provide detailed output |
-c, --cursor | Create .cursor symlink for Cursor editor integration |
-i, --index | Generate index.md files from frontmatter in ai/ subfolders |
churn | Rank files by hotspot score — see documentation |
-h, --help | Display help information |
--version | Show version number |
# Basic usage
npx aidd # Current directory
npx aidd my-project # Specific directory
# Hotspot analysis (see ai/skills/aidd-churn/SKILL.md for details)
npx aidd churn # Rank files by hotspot score (top 20, 90-day window)
npx aidd churn --days 30 --top 10 --min-loc 100 --json
# Preview and force options
npx aidd --dry-run # See what would be copied
npx aidd --force --verbose # Overwrite with details
# Cursor editor integration
npx aidd --cursor # Create .cursor symlink
npx aidd my-project --cursor --verbose
# Generate index files
npx aidd --index # Regenerate ai/ index.md files
npx aidd --index --verbose # Show all generated files
# Multiple projects
npx aidd frontend-app
npx aidd backend-api
Skills are reusable agent workflows that extend AIDD with specialized capabilities. Invoke them by name in any AI coding assistant.
npx aidd churn, interpret the ranked results, and recommend specific files to review or refactor with concrete strategies. Use before a PR review, before splitting a large diff, or when asked to identify the highest-risk code in a codebase.After running the CLI, you'll have a complete ai/ folder:
your-project/
├── ai/
│ ├── commands/ # Workflow commands
│ │ ├── help.md # List available commands
│ │ ├── plan.md # Project planning
│ │ ├── review.md # Code reviews
│ │ ├── task.md # Task management
│ │ └── ...
│ ├── rules/ # Agent orchestration rules
│ │ ├── agent-orchestrator.mdc
│ │ ├── javascript/ # JS/TS best practices
│ │ ├── frameworks/ # Redux, TDD patterns
│ │ ├── productmanager.mdc
│ │ ├── tdd.mdc
│ │ ├── ui.mdc
│ │ └── ...
│ └── ...
├── plan/ # Product discovery artifacts
│ ├── story-map/ # User journeys & personas (YAML)
│ ├── *-human-test.md # Human test scripts
│ └── *-agent-test.md # AI agent test scripts
└── your-code/
ai/rules/agent-orchestrator.mdc) - Coordinates multiple AI agentsai/rules/javascript/, ai/rules/tdd.mdc) - Best practices and patternsai/commands/) - Structured AI interaction templatesai/rules/productmanager.mdc) - User stories and journey mappingplan/story-map/) - User journeys, personas, and story maps (YAML format)plan/) - Human and AI agent test scripts generated from journeysai/rules/ui.mdc) - Design and user experience standardsThis system is designed to work with AI coding assistants:
The rules provide context and structure for more effective AI interactions.
The vision document (vision.md) is a critical component of AIDD that serves as the source of truth for AI agents working on your project.
AI agents are powerful but need context to make good decisions. Without a clear vision:
Create a vision.md file in your project root with the following sections:
# Project Vision
## Overview
Brief description of what this project does and who it's for.
## Goals
- Primary goal 1
- Primary goal 2
- ...
## Non-Goals (Out of Scope)
Things this project explicitly will NOT do.
## Key Constraints
- Technical constraints (e.g., must use specific frameworks)
- Business constraints (e.g., must be GDPR compliant)
- Performance requirements
## Architectural Decisions
Major technical decisions and their rationale.
## User Experience Principles
How the product should feel to users.
## Success Criteria
How we measure if the project is successful.
The AIDD system instructs agents to:
vision.md to understand project contextThis ensures that all AI-generated code and decisions align with your project's goals.
When you run the AIDD installer, it automatically creates (or updates) an AGENTS.md file in your project root. This file contains directives that help AI agents:
ai/ directory structure efficientlyindex.md files to understand folder contents without reading every fileaidd-custom/ — Project CustomizationThe installer also creates aidd-custom/config.yml in your project root. This folder is the place for project-specific overrides: custom skills, behavior configuration, and additional agent directives. Agents are instructed to read aidd-custom/index.md on startup so your customizations are always in context.
See docs/aidd-custom.md for all available options.
The AIDD CLI can automatically set up the AI agent system for Cursor editor users.
# Creates both ai/ folder AND .cursor symlink
npx aidd --cursor
# This creates:
# ai/ <- The complete AI system
# .cursor -> ai <- Symlink for Cursor integration
--cursor.cursor configuration--cursor.cursor folder: You already have Cursor rulesIf you already have a .cursor folder or use a different editor:
# 1. Clone without symlink
npx aidd my-project
For Cursor users with existing rules:
Reference the rules in your prompts or add to .cursor/rules:
See ai/rules/javascript/javascript.mdc for JavaScript best practices
See ai/rules/tdd.mdc for test-driven development
See ai/rules/productmanager.mdc for product management
For other editors (VS Code, Vim, etc.):
Reference rules directly in your AI assistant prompts:
Please follow the guidelines in ai/rules/javascript/javascript.mdc
Use the workflow from ai/commands/task.md
Verify Installation
# Check that ai/ folder was created
ls ai/
# Verify key files exist
ls ai/rules/please.mdc
ls ai/commands/
Common Issues
# If .cursor already exists, use --force
npx aidd --cursor --force
# Preview what --cursor will do
npx aidd --cursor --dry-run --verbose
# Clear npx cache if installation fails
npx clear-npx-cache
npx aidd --cursor
# Check Node version (requires 16.0.0+)
node --version
Updating
# Simply run aidd again to get latest version
npx aidd --force
Uninstalling
# Remove the ai/ folder
rm -rf ai/
# Remove .cursor symlink if it exists
rm .cursor
MIT © ParallelDrive
Public-access, recorded trainings published to YouTube on a (mostly) weekly basis, covering AIDD Framework workflows and software engineering in general. We meet at 3:00pm PT every Tuesday.
📖 Browse all training sessions →
We welcome contributions! Follow the Development Workflow above, and see CONTRIBUTING.md for details.
Start building with AI orchestration today:
npx aidd --cursor
FAQs
The standard framework for AI Driven Development.
The npm package aidd receives a total of 176 weekly downloads. As such, aidd popularity was classified as not popular.
We found that aidd demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Attackers compromised Trivy GitHub Actions by force-updating tags to deliver malware, exposing CI/CD secrets across affected pipelines.
Security News
ENISA’s new package manager advisory outlines the dependency security practices companies will need to demonstrate as the EU’s Cyber Resilience Act begins enforcing software supply chain requirements.
Research
/Security News
We identified over 20 additional malicious extensions, along with over 20 related sleeper extensions, some of which have already been weaponized.