AI 工作操作系统 — 给 AI Agent 一个完整的工程任务执行框架
就像操作系统给应用程序提供文件系统、内存管理、进程调度一样，ai-dev-guidelines 给 AI Agent 提供：
| 能力 | 说明 | 对应模块 |
|---|---|---|
| 标准化工作流 | 7 种路由（dev/fix/analyze/audit/self-fix/chat/resume），含子类型变体 | version/v4/specs/ |
| 持久化记忆 | 三层记忆架构（Agent 日记 + 需求记忆 + 全局 SUMMARY），跨会话状态恢复 | .ai-memory/ + reports/ |
| 行为约束 | 14 条约束（P2 安全底线 S01 |
version/v4/specs/common.md §6 |
| 文档模板 | 18 个结构化模板，输出格式统一 | version/v4/templates/ |
| 规范自修复 | 两级机制（自动级直接修复 / Pending 级积压队列），N13 双层合规检查 | version/v4/specs/self-fix/ |
| 意图识别 | 三问判断法，语义理解驱动路由，不依赖关键词匹配 | version/v4/specs/intent.md |
- ❌ 不是 Vibe Coding — Vibe Coding 追求"忘记代码的存在"，本项目追求 AI 在工程化护栏内的可控、可追溯、可恢复的执行
- ❌ 不是提示词模板 — 不是几条规则让 AI 照做，而是完整的执行框架
- ❌ 不是编码规范 — 不是 ESLint/Prettier 那样约束代码风格
- ❌ 不是项目管理工具 — 不是 Jira/Linear 的替代品
ai-dev-guidelines 是一套 AI 辅助开发的 SOP（标准操作程序）。
| 传统 SOP（面向人） | ai-dev-guidelines（面向 AI Agent） |
|---|---|
| 纸质/文档化的操作步骤 | Markdown 编码的执行规范（AI 可直接解析） |
| 人阅读 → 人执行 | AI 读取 → AI 执行 → 人确认关键决策 |
| 靠培训和监督确保合规 | 靠 N13 双层合规检查 + 14 条约束自动确保 |
| 出错靠事后审计发现 | 出错靠规范自修复（N11 self-fix）实时修正 |
SOP 五要素对照：
| SOP 要素 | 对应模块 | 说明 |
|---|---|---|
| 目的 | README + §1 | 让 AI Agent 在工程化护栏内执行任务 |
| 范围 | §2 意图识别 | 6 种意图路由覆盖开发全场景 |
| 步骤 | §1 消息管线 + workflows/ | N01→N14 完整流程 + CP1→CP2→CP3 确认点 |
| 职责 | §8 Agent 协同 | 多 Agent 目录隔离 + 标识检测 |
| 记录 | §5 记忆 + §6 报告 | 5+1 阶段跨会话记忆 + 报告自动生成 |
无状态模式（传统）:
用户: "继续上次的工作"
AI: "抱歉，我不记得上次做了什么"
ai-dev-guidelines:
用户: "继续"
AI: → 读取记忆 → 恢复上下文 → 无缝继续
多个 AI（Copilot / Claude / GPT）可以在同一项目上并行工作，通过目录隔离和记忆共享避免冲突。
v4 采用两层半架构设计，平衡 Token 效率与规范完整性：
RULES.md（≤ 150 行，轻量入口层）
├── 主线 Mermaid 流程图（含 NODE_META 路由注释）
├── P2 安全底线引用（→ specs/safety.md）
└── NODE_META：每个节点的 spec 文件路径 + fallback 路径
specs/（规范库层，~60 个文件，按需加载）
├── common.md（通用规范 / 14 条约束 / 优先级规则）
├── safety.md（安全底线 S01~S06，不可覆盖）
├── dev/ fix/ audit/ analyze/ self-fix/（工作流规范）
└── 扩展规范（routing / memory / report / compliance 等）
tenants/<id>/specs/（多租户覆盖层，可选）
AI 读取 RULES.md 后，通过 NODE_META 的 spec 字段按需加载当前节点的规范文件，每次会话只加载实际执行所需的 spec，而非全量读取。
ai-dev-guidelines/
├── .github/ # 🚪 入口文件
│ └── copilot-instructions.md # AI 入口指引（v4，当前活跃）
├── version/ # 📦 版本化规范目录
│ ├── v4/ # 🤖 v4 规范体系（活跃）
│ │ ├── RULES.md # 轻量入口（≤ 150 行）
│ │ ├── specs/ # 规范库（~60 个文件，按需加载）
│ │ ├── templates/ # 18 个文档模板
│ │ ├── tenants/ # 多租户定制规范目录
│ │ ├── tools/ # 辅助脚本（v4-full-audit.js 等）
│ │ └── website/ # 规范文档站（rspress）
│ ├── v3/ # 📦 v3 归档
│ │ ├── RULES.md # v3 单文件权威规范（~620 行）
│ │ ├── workflows/ # v3 工作流定义
│ │ └── templates/ # v3 文档模板
│ └── v2/ # 📦 v2 归档
├── tools/ # 🔧 根级自动化工具（bump-version.js 等）
├── changelogs/ # 📜 版本变更详情
├── CHANGELOG.md # 📋 版本概览索引
└── README.md # 📖 本文件
项目工作产出（记忆/报告/需求文档）存放在工作目录的
projects/<project>/下，与规范仓库分离。
- 将
ai-dev-guidelines/放入你的 workspace - 在
.github/copilot-instructions.md中添加入口指引（参考本项目.github/copilot-instructions.md） - AI 会自动读取
version/v4/RULES.md并按流程执行
# 1. 在工作目录创建项目产出目录
mkdir -p projects/<your-project>/profile
# 2. 复制项目模板
cp version/v4/templates/project-profile.md projects/<your-project>/profile/README.md
# 3. 编辑项目规范
# 填写 projects/<your-project>/profile/README.md
# 4. AI 自动识别
# AI 在收到任务时会自动读取对应项目规范v4 采用两层半架构，核心规范文件分布在 version/v4/specs/ 目录下。更新规范时：
- 修改规范：使用 self-fix 工作流（N11），非白名单变更写入
specs/audit/pending-fixes.md积压队列 - 添加规范：在对应工作流目录下新建 spec 文件，并在 RULES.md 或 common.md §2 中更新节点元数据
- 一致性检查：运行
node version/v4/tools/v4-full-audit.js检查数值引用一致性
v4 流程图（RULES.md）不包含 click URL，无需维护仓库 URL 耦合问题（v3 遗留问题已消除）。
| 原则 | 说明 |
|---|---|
| AI 是第一用户 | 所有设计以"AI 能否无歧义执行"为标准 |
| 有状态 > 无状态 | 消息驱动记忆，AI 拥有跨会话工作记忆 |
| 两层半架构 | 轻量入口（≤150 行）+ 规范库（按需加载）+ 租户覆盖，兼顾效率与完整性 |
| 约束是护栏不是枷锁 | 14 条约束防止 AI 犯人类会犯的错 |
| 意图驱动 > 关键词匹配 | 三问判断法做语义理解，不依赖关键词触发 |
| 指标 | 数据 |
|---|---|
| 当前版本 | v4.0.0 |
| 核心规范 | RULES.md（≤ 150 行）+ specs/（~60 个文件） |
| 路由 | 7 种（dev/fix/analyze/audit/self-fix/chat/resume） |
| 模板 | 18 个 |
| 约束 | 14 条（P2 安全底线 S01 |
| 接入项目 | 5+ 个 |
| 版本 | 架构 | 特点 |
|---|---|---|
| v1.x | 基础框架 | 核心工作流 + 确认点机制 |
| v2.x | 多文件分散 | 三层递进架构 · 13 种工作流 · 29 个模板 · 22 条约束 |
| v3.0 | 单文件权威 | RULES.md 单文件 · 6 种路由 · 8 个模板 · 三问判断法 · 全流程 Mermaid 流程图 |
| v4.0 | 两层半架构 | RULES.md ≤150行 · specs/规范库（~60文件）· NODE_META 路由 · 7种路由 · 18模板 · 14约束 · 多租户 · 规范文档站 |
详见 变更日志
MIT