ai-dev

ai-dev 是面向 Codex 等 Coding Agent 的 AI Native Development Protocol 初始化器。它只安装开发规则、状态模板和持久工作目录；日常开发仍由开发者与 Agent 通过自然语言完成。

快速开始

pnpm add -D @zhouyijun/dotai
pnpm exec ai-dev init --dry-run
pnpm exec ai-dev init
pnpm exec ai-dev init --refresh

然后告诉 Agent 开始一项需求：

开始需求：订单撤回

Agent 会先创建空的 requirement.md，由开发者填写并确认。随后依次完成 Analyze、Plan、计划批准、Task 拆分、任务清单批准、实现、Scoped Verify/Review、Finding/Fix Loop 和 Work-level Gate。不需要学习额外的日常 CLI 命令。批准 Plan 只会生成任务清单；只有再次明确批准当前任务清单后，Agent 才能开始编码。

初始化结果

AGENTS.md
.ai/
├── config.yaml
├── rules/
│   ├── principles.md
│   ├── development.md
│   ├── tasks.md
│   ├── verification.md
│   └── review.md
├── templates/
│   ├── requirement.md
│   ├── plan.md
│   ├── state.yaml
│   ├── tasks.yaml
│   └── findings.yaml
└── work/
    └── .gitkeep

• rules 定义 Agent 应该怎样工作。
• templates 定义 Requirement、Plan、Task、Finding 和 Gate 的数据结构。
• work 保存 .ai/work/<work-id>/ 下的当前真实状态；对话不是状态源。
• config.yaml 保存检测到的项目验证命令。

init 只创建缺失文件，已有 AGENTS.md 仅追加或刷新 ai-dev:start/end 区块，未带 managed marker 的 .ai 用户文件绝不覆盖。生成的 AGENTS.md、Rules 和 Markdown 产物模板使用中文；YAML 字段、状态值和路径保持稳定协议。--dry-run 会列出 create/modify/keep 计划并以 No files changed. 结束。

dotai 作为兼容命令别名仍可使用。项目已经初始化后，可执行 ai-dev init --refresh 重新安装最新的根 Router、Rules、Templates 和检测配置；.ai/work/ 中的工作状态不会被修改。只有根 AGENTS.md 包含 ai-dev 当前或旧版 managed marker 时才会覆盖协议文件，未初始化项目中的同路径用户文件仍会保留。

开始一项新需求时，Agent 只创建工作目录、空的 requirement.md 和处于 requirement 阶段的 state.yaml。plan.md、tasks.yaml、findings.yaml 以及验证/评审目录会在进入对应阶段后创建；验证与评审记录分别直接放在 verification/ 和 review/，不再使用 runs/ 中间层。

分析完成后生成的 plan.md 同时承担轻量技术设计职责：需要说明现状证据、目标架构、模块边界、数据流、接口与数据模型、关键技术决策、兼容迁移、回滚和验证方案。设计深度应与改动规模相称，不要求简单改动机械填写无关内容。

本地开发

pnpm install
pnpm verify
pnpm dev -- help

项目要求 Node.js 20+、严格 TypeScript、ESM，并保持零运行时依赖。