AI-Driven Development Specification (ADDS)

Agent-driven development framework — enabling AI Agents to autonomously complete project development across multiple context windows

Inspired by Anthropic's research and LangChain's harness engineering.

中文文档 | English Documentation

Core Principles

Multi-Agent Team Model — PM, Architect, Developer, Tester, Reviewer agents
State-Driven — .ai/feature_list.md is the single source of truth
Incremental Development — One feature at a time, never one-shot
Clean Handoffs — Every session leaves a mergeable state
Evidence-First — Prove features work with tool-based evidence
Regression Protection — Verify existing features before adding new ones

核心理念

ADDS 是一个 AI 驱动的软件开发规范，旨在让 AI Agent 能够自主完成项目开发。通过架构约束而非 AI 理解来保证行为的确定性和可靠性。

核心改进

基于 Claude Code 的设计思路，ADDS 实现了从"规范文档"到"可执行规范系统"的转变：

改进项	传统方法问题	ADDS 解决方案
系统提示词	AI 需阅读规范	分段式自动注入
状态管理	依赖 AI 记住	Agent Loop 强制执行
代理选择	AI 判断	自动路由决策
状态稳定性	可能抖动	锁存机制保护
安全性	依赖 AI 判断	失败关闭 + 三级权限
可观测性	仅日志	合规性追踪
上下文管理	依赖模型窗口	两层压缩 + 两层记忆
记忆延续	每次会话失忆	进化记忆 + 链式 Session

核心特性：系统提示词注入 • Agent Loop 状态机 • 锁存保护 • 失败关闭 • 合规追踪 • 两层压缩 • 两层记忆 • 三级权限

快速开始

要求：Python 3.9+

5 步上手（5 分钟）

# 1. 初始化项目
python3 scripts/adds.py init

# 2. 编辑功能列表
vim .ai/feature_list.md

# 3. 查看推荐代理
python3 scripts/adds.py route

# 4. 启动开发循环
python3 scripts/adds.py start

# 5. 查看进度
python3 scripts/adds.py status

完整指南：quick-start.md | English

核心特性

1. 分段式系统提示词

[静态区] identity, core_principles
  → 所有项目相同，可全局缓存
  
[边界标记] STATIC_BOUNDARY
  
[动态区] state_management, feature_workflow
  → 项目特定内容，按需生成

优势：AI 无需理解规范，自动注入约束，节省 token 成本

2. Agent Loop 状态机

while True:
    ① 上下文预处理    # 强制检查 feature_list.md
    ② 路由决策        # 自动选择代理
    ③ 执行代理        # 权限检查 → 确定性执行
    ④ 状态更新        # 锁存保护
    ⑤ 终止判定        # 明确的终止条件

优势：状态驱动而非 AI 判断，防止非法状态转换

3. 两层压缩 (P0-2)

Layer 1: 工具输出超阈值 → 保存 .log + 替换为摘要（实时，无 API 调用）
Layer 2: 上下文超 80% → LLM 结构化摘要 + .mem 归档 + 新 Session

优势：错误信号永不压缩，历史数据归档不丢失

4. 两层记忆 (P0-3)

Layer 1: index.mem（固定记忆 + 索引线索）→ 始终注入上下文
Layer 2: .mem 文件（链式归档）→ 按需加载

优势：记忆进化/排毒/角色化/反思协议/回归警报/强制复读

5. 三级权限 (P0-4)

Allow  → 自动放行（ls, cat, python, git status...）
Ask    → 需确认（rm, pip install, git push...）
Deny   → 直接拒绝（sudo, mkfs, 写入 /etc...）

优势：四种模式（default/plan/auto/bypass）+ 死循环防护 + 会话级覆盖

6. 失败关闭机制

if not pending_features:
    raise RuntimeError("停止而非猜测")  # 失败关闭

优势：默认最安全行为，避免错误累积

7. 合规性追踪

✅ 检测"一次一个功能"违规
✅ 验证状态转换合法性
✅ 监控代理边界约束
✅ 量化合规分数

优势：主动检测违规，而非依赖 AI 报告

架构

┌──────────────────────────────────────────────────────────┐
│                    CLI 入口层                             │
│  adds.py — init/start/status/route/mem/session/skill/    │
│            schedule/executor/gateway/fork/perm 命令        │
├──────────────────────────────────────────────────────────┤
│                 Agent Loop 调度层                          │
│  agent_loop.py — 状态机 + 路由 + 迭代控制                  │
│  system_prompt_builder.py — 分段式 SP 构建 + 记忆注入       │
│  compliance_tracker.py — 合规追踪                          │
│  skill_manager.py (P1) — 技能渐进式披露                     │
│  loop_state.py (P1) — 韧性状态机                           │
├────────┬──────────┬─────────────┬─────────────────────────┤
│ P0-1   │ P0-2     │ P0-3        │ P0-4                   │
│ 模型层  │ 压缩层   │ 记忆层       │ 权限层                  │
│        │          │             │                         │
│ model/ │ context_ │ memory_     │ permission_             │
│  API   │ compactor│ manager     │  manager.py             │
│  CLI   │ token_   │ conflict_   │                         │
│  SDK   │ budget   │ detector    │                         │
│        │ session_ │ retriever   │                         │
│        │ manager  │ detox       │                         │
│        │ summary_ │ consistency │                         │
│        │ decision │ _guard      │                         │
│        │ _engine  │ role_       │                         │
│        │          │ injector    │                         │
│        │          │ memory_cli  │                         │
│        │          │ priority_   │                         │
│        │          │ sorter      │                         │
├────────┴──────────┴─────────────┴─────────────────────────┤
│                 P2 高级特性层                              │
│  scheduler.py (P2-1) — 定时调度系统                        │
│  executor_backend.py (P2-2) — 执行后端隔离                  │
│  gateway.py (P2-3) — 多平台通信网关                        │
│  agent_fork.py (P2-4) — Fork 子 Agent                     │
├──────────────────────────────────────────────────────────┤
│                    基础设施层                               │
│  .ai/sessions/ — .ses/.log/.mem 文件存储                    │
│  .ai/memories/ — SKILLS/ + 角色化记忆                       │
│  .ai/settings.json — 全局配置                               │
└──────────────────────────────────────────────────────────┘

详见：架构文档 | 改进路线图

文档导航

🚀 新用户（5-30 分钟）

文档	时间	内容
快速开始 \| EN	5分钟	5步上手指南
使用示例 \| EN	15分钟	实际项目示例
核心规范	10分钟	Agent 必读规范

🎯 技术人员（30-120 分钟）

文档	时间	内容
改进路线图	60分钟	P0/P1/P2 完整规划
架构设计	30分钟	P0 架构与数据流
完整规范	60分钟	技术规范全文

📊 项目管理者（10-30 分钟）

文档	时间	内容
快速开始	10分钟	快速上手指南
使用示例	30分钟	实践案例和最佳实践

项目结构

ai-driven-dev-spec/
├── scripts/                        # 核心实现
│   ├── adds.py                     # CLI 主工具
│   ├── agent_loop.py               # Agent Loop 状态机
│   ├── system_prompt_builder.py    # 提示词构建器
│   ├── compliance_tracker.py       # 合规追踪器
│   ├── agents.py                   # 5 个代理实现
│   │
│   ├── model/                      # [P0-1] 模型调用层
│   │   ├── base.py                 # ModelInterface 抽象基类
│   │   ├── factory.py              # 交互式模型工厂
│   │   ├── api_adapter.py          # API 调用适配器
│   │   ├── cli_adapter.py          # CLI 工具适配器
│   │   ├── sdk_adapter.py          # SDK 适配器
│   │   ├── task_dispatcher.py      # CLI 任务派发器
│   │   ├── skill_generator.py      # 技能自动生成器
│   │   └── providers/              # Provider 注册表
│   │       ├── minimax.py
│   │       ├── codebuddy.py
│   │       └── registry.py
│   │
│   ├── token_budget.py             # [P0-2] Token 预算管理器
│   ├── session_manager.py          # [P0-2] Session 文件管理
│   ├── summary_decision_engine.py  # [P0-2] 摘要策略决策引擎
│   ├── context_compactor.py        # [P0-2] 两层压缩引擎
│   │
│   ├── memory_manager.py           # [P0-3] 记忆管理器
│   ├── memory_conflict_detector.py # [P0-3] 记忆冲突检测器
│   ├── memory_retriever.py         # [P0-3] 记忆检索接口
│   ├── memory_detox.py             # [P0-3] 记忆排毒引擎
│   ├── consistency_guard.py        # [P0-3] 一致性守护
│   ├── role_memory_injector.py     # [P0-3] 角色感知记忆注入器
│   ├── memory_cli.py               # [P0-3] CLI 记忆管理子命令
│   ├── index_priority_sorter.py    # [P0-3] 优先级排序器
│   │
│   ├── permission_manager.py       # [P0-4] 权限管理器
│   │
│   ├── skill_manager.py            # [P1] 技能渐进式披露
│   ├── loop_state.py              # [P1] Agent Loop 韧性状态机
│   │
│   ├── scheduler.py               # [P2-1] 定时调度系统
│   ├── executor_backend.py        # [P2-2] 执行后端隔离
│   ├── gateway.py                 # [P2-3] 多平台通信网关
│   ├── agent_fork.py              # [P2-4] Fork 子 Agent
│   │
│   ├── test_p0_2.py               # P0-2 单元测试 (57 tests)
│   ├── test_p0_3.py               # P0-3 单元测试 (74 tests)
│   ├── test_p0_4.py               # P0-4 单元测试 (69 tests)
│   ├── test_p0_integration.py     # P0 集成测试 (25 tests)
│   ├── test_p1_skill.py           # P1 技能测试 (30 tests)
│   ├── test_p1_resilience.py      # P1 韧性测试 (10 tests)
│   ├── test_p2_scheduler.py       # P2-1 调度测试 (64 tests)
│   ├── test_p2_executor.py        # P2-2 执行后端测试 (63 tests)
│   ├── test_p2_gateway.py         # P2-3 网关测试 (46 tests)
│   └── test_p2_fork.py            # P2-4 Fork 测试 (26 tests)
│
├── .ai/                            # 项目状态
│   ├── CORE_GUIDELINES.md          # 核心规范
│   ├── architecture.md             # 架构文档
│   ├── feature_list.md             # 功能列表
│   ├── progress.md                 # 进度日志
│   ├── settings.json               # 全局配置
│   ├── sessions/                   # Session + 记忆文件
│   ├── memories/                   # 技能库 + 角色化记忆
│   └── roadmap/                    # 改进路线图
│
├── docs/                           # 文档
│   ├── guide/                      # 使用指南
│   ├── references/                 # 参考资料
│   ├── specification.md            # 完整技术规范
│   └── en/                         # 英文文档
│
├── templates/                      # 模板文件
├── schemas/                        # JSON Schema
├── setup.py                        # 安装脚本
├── CHANGELOG.md                    # 变更日志
├── README.md                       # 项目说明
└── LICENSE                         # 许可证

测试结果

P0+P1+P2 测试: 424 个测试 | 通过率: 100%

✅ P0 单元测试 (225 tests)
   test_p0_2 (57 tests) - 上下文压缩层
   test_p0_3 (74 tests) - 记忆系统
   test_p0_4 (69 tests) - 权限管理器
   test_p0_integration (25 tests) - P0 四层协同集成测试

✅ P1 增强测试 (30+ tests)
   test_p1_skill.py (30 tests) - 技能渐进式披露
   test_p1_resilience.py (10 tests) - Agent Loop 韧性增强

✅ P2 高级特性测试 (199 tests)
   test_p2_scheduler.py (64 tests) - 定时调度系统
   test_p2_executor.py (63 tests) - 执行后端隔离
   test_p2_gateway.py (46 tests) - 多平台通信网关
   test_p2_fork.py (26 tests) - Fork 子 Agent 路径

运行测试：

cd scripts
python3 -m unittest test_p0_2 test_p0_3 test_p0_4 test_p0_integration test_p1_skill test_p1_resilience test_p2_scheduler test_p2_executor test_p2_gateway test_p2_fork -v

设计原则（参考 Claude Code）

ADDS 完全实现了 Claude Code 的六条驾驭工程原则：

原则	实现方式	代码位置
提示词即控制面	SystemPromptBuilder	`system_prompt_builder.py`
缓存感知设计	静态/动态边界	`system_prompt_builder.py`
失败关闭，显式开放	SafetyDefaults	`agent_loop.py`
A/B测试一切	ComplianceTracker	`compliance_tracker.py`
先观察再修复	违规追踪	`compliance_tracker.py`
锁存以求稳定	ProjectLatches	`agent_loop.py`

参考书籍：《驾驭工程：从 Claude Code 源码到 AI 编码最佳实践》

常用命令

# 项目管理
python3 scripts/adds.py init      # 初始化项目
python3 scripts/adds.py status    # 查看进度
python3 scripts/adds.py route     # 推荐代理

# 开发循环
python3 scripts/adds.py start     # 启动 Agent Loop
python3 scripts/adds.py start --perm default  # 指定权限模式

# Session 管理
python3 scripts/adds.py session list     # Session 列表
python3 scripts/adds.py session restore <id>  # 恢复 Session

# 记忆管理
python3 scripts/adds.py mem status       # 记忆状态
python3 scripts/adds.py mem audit        # 交互式审查
python3 scripts/adds.py mem prune --module auth  # 清理记忆

# 技能管理 (P1)
python3 scripts/adds.py skill list        # 技能列表
python3 scripts/adds.py skill view <name>  # 技能详情

# 定时调度 (P2-1)
python3 scripts/adds.py schedule add "构建" --cron "@daily" --type command --command "make build"
python3 scripts/adds.py schedule list     # 任务列表
python3 scripts/adds.py schedule daemon   # 守护进程

# 执行后端 (P2-2)
python3 scripts/adds.py executor list     # 后端列表
python3 scripts/adds.py executor health   # 健康检查

# 通信网关 (P2-3)
python3 scripts/adds.py gateway list      # 渠道列表
python3 scripts/adds.py gateway send --type notification --subject "构建完成"

# Fork 子 Agent (P2-4)
python3 scripts/adds.py fork run <task>   # 派生执行
python3 scripts/adds.py fork parallel <task1> <task2>  # 并行执行

# 权限管理
python3 scripts/adds.py perm status      # 权限状态
python3 scripts/adds.py perm rules       # 权限规则
python3 scripts/adds.py perm mode auto   # 切换模式

# 测试验证
cd scripts && python3 -m unittest test_p0_2 test_p0_3 test_p0_4 test_p0_integration test_p1_skill test_p1_resilience test_p2_scheduler test_p2_executor test_p2_gateway test_p2_fork -v

许可证 & 合规说明

本项目采用 GNU General Public License v3.0 (GPLv3) 许可证。

详见 LICENSE 文件。

致谢

本项目设计参考了 Claude Code 的架构思路，特此致谢。

联系方式

Issues: GitHub Issues
Discussions: GitHub Discussions

项目状态：✅ P0 + P1 + P2 全部完成 (15/15) P0 进度：4/4 模块已完成 + 集成测试通过 P1 进度：2/2 功能已完成 P2 进度：4/4 功能已完成 测试通过率：100% (424/424)

中文文档

English Documentation

Full English documentation: README-en.md

Detailed docs:

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

AI-Driven Development Specification (ADDS)

Core Principles

核心理念

核心改进

快速开始

5 步上手（5 分钟）

核心特性

1. 分段式系统提示词

2. Agent Loop 状态机

3. 两层压缩 (P0-2)

4. 两层记忆 (P0-3)

5. 三级权限 (P0-4)

6. 失败关闭机制

7. 合规性追踪

架构

文档导航

🚀 新用户（5-30 分钟）

🎯 技术人员（30-120 分钟）

📊 项目管理者（10-30 分钟）

项目结构

测试结果

设计原则（参考 Claude Code）

常用命令

许可证 & 合规说明

致谢

联系方式

中文文档

English Documentation

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 103 Commits
.ai		.ai
docs		docs
schemas		schemas
scripts		scripts
templates		templates
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README-en.md		README-en.md
README.md		README.md
pyproject.toml		pyproject.toml
setup.py		setup.py
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

AI-Driven Development Specification (ADDS)

Core Principles

核心理念

核心改进

快速开始

5 步上手（5 分钟）

核心特性

1. 分段式系统提示词

2. Agent Loop 状态机

3. 两层压缩 (P0-2)

4. 两层记忆 (P0-3)

5. 三级权限 (P0-4)

6. 失败关闭机制

7. 合规性追踪

架构

文档导航

🚀 新用户（5-30 分钟）

🎯 技术人员（30-120 分钟）

📊 项目管理者（10-30 分钟）

项目结构

测试结果

设计原则（参考 Claude Code）

常用命令

许可证 & 合规说明

致谢

联系方式

中文文档

English Documentation

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages