AI Dev OS

Turn tacit developer knowledge into explicit, enforceable rules for AI-assisted coding.

Coding rules framework for AI assistants — Claude Code, Cursor, and Kiro

> /ai-dev-os-check

## AI Dev OS Check & Fix Report
- Files checked: 12
- ✅ Passed: 45 / 🔧 Fixed: 3 / ⚠️ Manual Review: 1

| # | File              | Rule         | What was fixed              |
|---|-------------------|--------------|-----------------------------|
| 1 | route.ts:42       | security.md  | Added rate limiting         |
| 2 | user-card.tsx:7   | naming.md    | Renamed to kebab-case       |
| 3 | action.ts:15      | validation.md| Added .refine() for dueDate |

Why AI Dev OS?

Your AI writes code that looks right — but violates team conventions. Your coding standards live in senior developers' heads, not in AI context.

AI Dev OS solves this by making tacit knowledge explicit:

• 75% survives tool migrations — Rules are tool-independent (L1–L3). Switch Claude Code → Kiro → Cursor freely
• Rules improve over time — Harvest rules from real code reviews, not hypothetical ideals (Rule Harvesting)
• Near-zero cost — 3-5 static rules in context + comprehensive dynamic check & fix on demand (benchmark: 96.9/100)
• Pure Markdown — No DSL, no compilation. Fork, modify, and audit every rule

AI Dev OS complements your AI tool — it doesn't replace it. Claude Code, Kiro, and Cursor handle code generation; AI Dev OS handles the rules they follow.

Quick Start

npx ai-dev-os init

Pick a language (typescript / python) and a tool (claude-code / kiro / cursor).

# Non-interactive:
npx ai-dev-os init --rules typescript --plugin claude-code

CLI details | Manual setup | Choose Rules | Choose Plugin

Lifespan Layers — The 4-Layer Model

Layer	Name	Lifespan	Purpose
L1	Philosophy	2-5 years	Core values that transcend tools and languages
L2	Decision Criteria	1-3 years	Design and architecture decision criteria
L3	Guidelines	6-12 months	Concrete, verifiable coding rules
L4	AI Frames	2-4 months	Tool-specific configurations and workflows

Upper layers are abstract and stable; lower layers are concrete and volatile. When you switch tools, L1–L3 (75%) stay intact — only L4 changes.

Key Concepts

Specificity Cascade (rule conflict resolution) — When rules conflict, the most specific wins (like CSS specificity). Framework rules > common rules > project conventions > principles > philosophy. → Details

Rule Harvesting (bottom-up rule discovery) — Don't write rules top-down. Let AI code → review gaps → harvest into rules. Grounded in real experience. → Details

Guideline Capital (guidelines as intellectual assets) — Guidelines are intellectual capital, not disposable prompts. Unlike Technical Debt (liability), Guideline Capital is an asset that compounds. → Details

Two-Tier Context Strategy (generate + verify + fix) — Load only 3-5 project-specific files in CLAUDE.md (~8K tokens). Verify all rules post-generation via /ai-dev-os-check. Benchmark data shows this approach scores 96.9/100, while loading 10+ files scores lower than no guidelines at all. → Details

Works With

AI Dev OS provides a structured approach to writing effective AI coding rule files:

• Claude Code — via CLAUDE.md and custom skills (plugin)
• Kiro — via AGENTS.md and steering rules (plugin)
• Cursor — via .cursorrules and .mdc files (plugin)

Ecosystem

Repository	Description
ai-dev-os (this repo)	Framework specification and theory
rules-typescript	TypeScript / Next.js / Node.js guidelines
rules-python	Python / FastAPI guidelines
plugin-claude-code	Skills, Hooks, and Agents for Claude Code
plugin-kiro	Steering Rules and Hooks for Kiro
plugin-cursor	Cursor Rules (.mdc)
cli	npx ai-dev-os init
benchmark	Quantitative benchmark — guideline impact data

Learn More

• 4-Layer Model | Dependency Rule | Specificity Cascade | Shelf-Life Model
• Tacit-to-Explicit Engineering | Classical Theories | Future-Proofing
• Framework Comparison | Guidelines vs Multi-Agent | Tool Migration
• Zenn Book: AI DEV OS (Japanese)

Directory Structure

ai-dev-os/
├── spec/                        # Framework Specification
│   ├── 4-layer-model.md         #   Lifespan Layers (4-layer model)
│   ├── dependency-rule.md       #   Dependency rule
│   ├── priority-cascade.md      #   Specificity Cascade
│   ├── shelf-life.md            #   Shelf-life model
│   └── governance.md            #   Governance model
├── theory/                      # Theoretical Background
├── getting-started/             # Getting Started Guide
└── docs/                        # Operation Guide & i18n

The actual guideline files (01_philosophy/ ... 04_ai-prompts/) are in the rules repositories, not in this core repo.

License

MIT

---

Languages: English | 日本語 | 简体中文 | 한국어 | Español