# Agent 工作流套件指南

[项目首页](../README.zh-CN.md) · [English Guide](guide.md)

一份面向通用软件项目的、**先评估再接入** 的 AI 辅助开发工作流指南。

## 仓库内容

- `README.md`：英文项目首页。
- `README.zh-CN.md`：中文项目首页。
- `docs/guide.md`：英文公开版文档。
- `docs/guide.zh-CN.md`：中文公开版文档。
- `skills/agent-workflow-kit`：英文 agent-facing Skill 包，采用 Codex-compatible 结构打包。
- `skills/agent-workflow-kit-zh-cn`：中文 agent-facing Skill 包，采用 Codex-compatible 结构打包。

这份文档适合开源项目、个人项目、团队项目和产品项目的维护者使用。它的目标不是要求所有项目都接入同一套工具，而是帮助维护者判断：

- 项目是否需要 AI 工作流
- 流程应该多轻还是多重
- 哪些工具应该接入
- 哪些工具不该接入
- AI agent 应该遵守哪些项目级规则

核心原则：

> 先评估项目风险，再选择能降低真实风险的最小工作流。

---

## 快速开始（30 秒版）

如果你只想尽快上手，不必读完全文：

1. 走一遍决策树（第 4 节），判断项目需要哪些层。
2. 用风险评分表（第 5 节）给项目打分，得到 0-16 分。
3. 按分数选工作流级别：0-4 最小 / 5-9 标准 / 10+ 完整（第 6 节）。
4. 从第 10 节复制对应级别需要的 `AGENTS.md` 块，填好项目的验证命令。
5. 用一个小改动验证流程是否顺畅，再正式推广。

其余章节是按需查阅的深入参考。一句话总结：**能可靠防住项目真实失败模式的最小工作流，就是最好的工作流。**

---

## 1. 这份文档解决什么问题

AI coding agent 可以显著提升开发速度，但也容易带来这些问题：

- 需求只存在聊天记录里，后续无法追踪
- agent 跳过澄清，直接写代码
- 没有测试或验证就宣称完成
- 为小改动引入大范围重构
- 多个工具各自生成一套计划，互相冲突
- 对账号、发布、抓取、外部平台等高风险操作缺少边界

这份指南提供一个分层方法：

- **规格层**：记录变更的原因、范围、设计、任务和归档
- **执行纪律层**：约束 AI 的澄清、测试、调试、审查和验证行为
- **专家审查层**：在产品、设计、工程、QA、安全、发布等关键节点做审查
- **工具底座层**：在团队需要时统一 skills、rules、hooks、MCP、记忆和安全配置

这些层都是可选的。项目不需要为了“显得专业”而接入全套。

---

## 2. 工具角色示例

下面是常见工具的分层方式。你可以用等价工具替换它们。

这些项目只是示例，用来说明每一层大致长什么样，不是强制要求，也不代表本指南背书或保证其质量。它们的成熟度和维护状况差异很大，部分由个人或小团队维护，可能改名、停更或失效。采用前请自行评估各仓库的活跃度、维护情况和安全性，并阅读上游官方文档。能用等价工具替换时，优先选择更成熟、更贴合项目风险的那个。

| 层级 | 示例工具 | URL | 作用 | 适合场景 |
|---|---|---|---|---|
| 规格层 | OpenSpec | https://github.com/Fission-AI/OpenSpec | 管理 proposal、spec、design、tasks、archive | 长期功能、行为变化、高风险自动化 |
| 规格层 | Spec Kit | https://github.com/github/spec-kit | 更正式的 spec-driven development 生命周期 | 团队规范、组织级 SDD、较大型项目 |
| 执行纪律层 | Superpowers | https://github.com/obra/superpowers | 约束澄清、计划、TDD、调试、审查、验证 | 大多数 AI 参与写代码的项目 |
| 专家审查层 | gstack | https://github.com/garrytan/gstack | 产品/工程/设计/QA/安全/发布审查 | 用户可见产品、复杂 UI、生产发布 |
| 工具底座层 | ECC | https://github.com/affaan-m/ECC | skills、rules、hooks、MCP、记忆、安全、多语言规则 | 多 agent、多工具、多语言团队 |

默认建议：

```text
先评估项目。
只有当变更需要长期记忆时，才引入规格层。
只要 AI 会改代码，就应该有执行纪律。
只有当项目风险足够高时，才引入专家审查或重型工具底座。
```

---

## 3. 适合谁

适合：

- 长期维护的软件项目
- AI agent 会直接写代码或改代码的项目
- 需求经常散落在聊天记录里的项目
- 需要多人或多 agent 协作的项目
- 有真实用户、生产发布、复杂 UI 或安全敏感逻辑的项目
- 希望把 AI 开发流程标准化的团队

不太适合：

- 一次性脚本
- 学习 demo
- throwaway prototype
- 很小且边界清晰的库
- AI 只用于解释代码、不会直接改代码的项目
- 流程成本明显大于项目风险的项目

---

## 4. 接入决策树

在安装任何工具或新增项目规则前，先走这棵决策树。

决策树负责定性，帮你判断项目需不需要某一层；下一节的风险评分负责定级，决定工作流和各层的力度。两者配合使用；若结论冲突，以风险评分为准。

```mermaid
flowchart TD
  Start([安装工具或新增项目规则前])
  Q1{"一次性脚本或 throwaway prototype？"}
  L0["不接正式 AI 工作流<br/>保留普通测试和人工 review"]
  Q2{"AI agent 会直接编辑代码吗？"}
  NotNeeded["可能不需要本指南"]
  Discipline["至少添加基础执行纪律"]
  Q3{"会有非平凡的功能、行为、<br/>架构、数据或自动化变更吗？"}
  Spec["考虑规格层"]
  TaskNotes["使用轻量任务记录"]
  Q4{"有真实用户、生产发布、复杂 UI、<br/>安全、账号、支付、抓取、<br/>发布或浏览器自动化吗？"}
  Review["考虑专家审查、<br/>安全审查或 QA 验证"]
  AvoidHeavy["避免过重流程"]
  Q5{"需要在 Claude、Codex、Cursor、<br/>OpenCode、Gemini 等多个 harness<br/>中保持一致行为吗？"}
  Harness["考虑工具底座层"]
  Simple["保持项目规则简单"]
  Score([然后进入第 5 节风险评分])

  Start --> Q1
  Q1 -- 是 --> L0
  Q1 -- 否 --> Q2
  Q2 -- 否 --> NotNeeded
  Q2 -- 是 --> Discipline --> Q3
  Q3 -- 是 --> Spec --> Q4
  Q3 -- 否 --> TaskNotes --> Q4
  Q4 -- 是 --> Review --> Q5
  Q4 -- 否 --> AvoidHeavy --> Q5
  Q5 -- 是 --> Harness --> Score
  Q5 -- 否 --> Simple --> Score
```

```text
这是一次性脚本或 throwaway prototype 吗？
  是 → 不接正式 AI 工作流。保留普通测试和人工 review。
  否 → 继续

AI agent 会直接编辑代码吗？
  否 → 可能不需要本指南。
  是 → 至少添加基础执行纪律。

项目会有非平凡的功能、行为、架构、数据或自动化变更吗？
  是 → 考虑规格层。
  否 → 使用轻量任务记录即可。

项目是否有真实用户、生产发布、复杂 UI、安全、账号、支付、抓取、发布或浏览器自动化？
  是 → 考虑专家审查、安全审查或 QA 验证。
  否 → 避免过重流程。

团队是否需要在 Claude、Codex、Cursor、OpenCode、Gemini 等多个 harness 中保持一致行为？
  是 → 考虑工具底座层。
  否 → 保持项目规则简单。
```

---

## 5. 项目风险评分

给项目打分，再选择工作流级别。评分是启发式工具，不是精确公式；维度和权重可按团队实际情况调整。

| 维度 | 0 分 | 1 分 | 2 分 |
|---|---|---|---|
| 生命周期 | 一次性 | 偶尔维护 | 长期产品 |
| 用户影响 | 仅作者使用 | 内部使用 | 公开用户/客户使用 |
| UI/体验 | 无 UI | 简单 UI | 复杂 UI/编辑器/仪表盘 |
| 发布风险 | 不发布 | 手动发布 | staging/production/CI 发布 |
| 安全/账号 | 无 | API key 或少量权限 | auth、cookie、token、用户数据、支付 |
| 外部平台 | 无 | 第三方 API | 抓取、发布、浏览器自动化 |
| 测试难度 | 单测足够 | 需要集成测试 | E2E、截图、可访问性、性能 |
| 协作复杂度 | 单人短期 | 单人长期 | 团队或多 agent 协作 |

建议：

| 分数 | 推荐级别 |
|---:|---|
| 0-4 | 最小工作流 |
| 5-9 | 标准工作流 |
| 10+ | 完整工作流 |

覆盖规则：

- 安全/账号/外部平台任一项为 2 分时，至少加入安全审查。
- UI/测试难度任一项为 2 分时，至少加入浏览器或 E2E 验证。
- 协作复杂度为 2 分时，必须有清晰的项目级 AI 规则。

---

## 6. 工作流级别

### Level 0：不接正式 AI 工作流

适合小脚本、实验、一次性原型，或 AI 不直接改代码的项目。

建议：

- 保留正常测试
- 人工 review diff
- 不为了流程新增额外文件

### Level 1：最小工作流

适合小型但会维护的项目。

添加简短的 `AGENTS.md` 或等价 AI 指令：

- AI 修改前必须先看项目结构
- AI 不得做无关重构
- 完成前必须运行相关测试
- 最终回复必须说明改了什么、验证了什么

规格层可选。专家工具通常不需要。

### Level 2：标准工作流

适合大多数 AI 会参与开发的软件项目。

建议：

- 添加基础 `AGENTS.md`
- 非平凡变更使用规格层
- 新功能和 bugfix 使用测试先行或 TDD
- 修 bug 前先查根因
- 完成标准必须基于证据

专家审查可选，只在关键节点使用。

### Level 3：完整工作流

适合生产产品、复杂应用、安全敏感系统或多 agent 团队。

建议：

- 非平凡变更必须使用规格层
- 执行纪律必须写入项目规则
- 高风险变更设置专家审查门
- 敏感代码必须做安全审查
- 用户可见流程必须做浏览器/E2E 验证
- 项目级 AI 规则提交到仓库
- 如需跨工具一致性，再接入工具底座层

---

## 7. 工具选择指南

### 规格层

当项目需要把需求和变更长期保存下来时，使用规格层。

适合：

- 需求需要跨越聊天上下文
- 多个变更可能并行
- 功能需要 proposal、design、tasks 和归档
- 希望 AI 按明确文档实现，而不是按一句模糊 prompt 实现

规格层不是只能选 OpenSpec。按项目风格选择：

| 选择 | 适合 | 不适合 |
|---|---|---|
| OpenSpec | 已有项目、个人或小团队、希望轻量迭代、brownfield 项目 | 需要非常正式的组织级 SDD 流程 |
| Spec Kit | 团队工程规范、组织级 spec-driven development、需要明确 constitution/spec/plan/tasks 阶段 | 小项目、快速探索、流程成本敏感的项目 |
| ADR/RFC/design docs | 架构决策、平台项目、需要人类审阅的设计讨论 | 需要细任务拆解和 agent 自动执行的工作流 |
| GitHub issues / project docs | 小型开源项目、轻量协作 | 复杂多阶段功能或高风险自动化 |
| 自建 `docs/changes/` | 想保持工具中立的团队 | 缺少维护者持续执行时容易漂移 |

默认建议：

- 一般项目默认先考虑 OpenSpec 或轻量 `docs/changes/`。
- 更正式的团队/企业/大型项目再考虑 Spec Kit。
- 小项目不需要为了“规格驱动”而引入专门工具。

不适合：

- 拼写、注释、小配置修正
- 一次性脚本
- 流程比改动本身还大

### 执行纪律层

只要 AI 会写代码或改代码，就建议有执行纪律。

Superpowers 是一个示例。关键行为是：

- 实现前先澄清
- 测试先行或至少测试伴随
- 从根因调试，而不是猜修
- 完成前 review diff
- 用具体命令或证据验证结果

不应过度用于：

- throwaway prototype
- 生成式代码实验
- 明确以探索速度优先的 spike

### 专家审查层

当项目存在产品、设计、QA、安全或发布风险时，使用专家审查。

gstack 是一个示例。常见审查点：

- 实现前产品/范围审查
- 实现前工程/设计审查
- 实现后代码审查
- 用户流程浏览器 QA
- 敏感流程安全审查
- 合并或部署前发布审查

不适合：

- 小型项目且测试边界清晰
- 没有用户可见或生产风险
- 流程明显拖慢探索

### 工具底座层

当团队需要更完整的 AI 操作层时，考虑工具底座。

ECC 是一个示例。此类工具可能包含：

- skills
- rules
- hooks
- MCP 配置
- 记忆/会话模式
- 安全扫描
- 多语言规则
- 跨 harness 行为一致性

不建议默认安装重型工具底座：

- 项目已经有足够流程
- 团队不需要 hooks 或跨工具一致性
- 代码库很小
- 维护者还没准备好管理额外行为

---

## 8. 工具冲突规则

多个 AI 工作流工具重叠时，只保留一个事实来源。

### 计划冲突

如果规格层已经有 proposal、design 和 tasks：

- 不要再生成第二套竞争计划
- 应该审查并改进现有 artifacts
- 如果实现范围变化，先更新规格 artifacts，再改代码

示例：

```text
好：
OpenSpec proposal → 专家审查 → 更新 OpenSpec tasks → 实现

坏：
OpenSpec proposal → 另起 autoplan → 又生成 implementation plan → 不知道听谁的
```

### TDD 和验证冲突

如果多个工具都定义了 TDD 或验证规则：

- 以项目 `AGENTS.md` 为准
- 只有当项目风险足够高时，才采用最严格规则
- 不要强制小脚本达到 80%+ coverage，除非项目明确需要

### 安全和外部操作

除非项目规则明确授权，否则外部操作需要用户确认。

包括：

- push commits
- open/merge PR
- deploy
- 发布到社交平台
- 发送邮件
- 修改生产数据
- 修改凭据
- 运行付费任务
- 操作真实第三方账号

高风险流程优先使用 report-only 审查。

### 现有项目规则优先

如果仓库已有 `AGENTS.md`、`CLAUDE.md`、Cursor rules、Copilot instructions 或团队规范：

- 先读取
- 保留原意
- 只补缺失部分
- 不经维护者同意，不覆盖现有规则

---

## 9. 项目评估清单

AI agent 在接入任何工作流前，应该先检查：

- `README.md`
- 现有 AI 指令：`AGENTS.md`、`CLAUDE.md`、`.cursor/rules`、`.github/copilot-instructions.md`
- 技术栈文件：`package.json`、`pyproject.toml`、`Cargo.toml`、`go.mod` 等
- 主要源码目录：`src/`、`app/`、`pages/`、`components/`、`lib/`
- 测试目录和配置：`tests/`、`spec/`、`e2e/`、Playwright/Cypress 配置
- CI 配置：`.github/workflows/`、`.gitlab-ci.yml`
- 部署配置：`vercel.json`、`Dockerfile`、`docker-compose.yml`、infra 配置
- 安全敏感代码：auth、token、cookie、支付、用户数据
- 平台自动化：抓取、发布、浏览器自动化、第三方账号流程

然后输出：

```markdown
## Agent Workflow Kit Decision

Project: <project-name>

### Summary

- Project type: <library / CLI / web app / automation / data pipeline / editor / internal tool / etc.>
- Lifecycle: <one-off / maintained / long-lived>
- Users: <author / internal / public / customers>
- Risk level: <low / medium / high>
- Score: <0-16>

### Decision

- Workflow level: <0 / 1 / 2 / 3>
- Spec layer: <none / light / required>
- Agent discipline: <none / recommended / required>
- Specialist review: <none / light / full>
- Harness/tooling pack: <none / optional / recommended>

### Reasoning

- <reason 1>
- <reason 2>
- <reason 3>

### Proposed Files

- <file to create/update, or "none">

### Verification Commands Found

- Install: `<command or unknown>`
- Test: `<command or unknown>`
- Lint/typecheck: `<command or unknown>`
- Build: `<command or unknown>`
- E2E/browser: `<command or unknown>`
```

除非维护者已经授权，否则不要在评估前直接安装工具或提交工作流文件。

---

## 10. AGENTS.md 模板

只复制项目需要的块，不要全量照搬。

### 基础块

```markdown
# AI Project Workflow

## Project Rules

Before changing code, inspect the existing project structure and follow local patterns.

Do not perform unrelated refactors, formatting churn, dependency upgrades, or broad cleanup unless explicitly requested.

If scope needs to expand, stop and explain why before continuing.

## Verification

Before completion, run the relevant checks and report the commands and results.

Project commands:

- Install dependencies: `<fill in>`
- Run tests: `<fill in>`
- Run lint/typecheck: `<fill in>`
- Build: `<fill in>`
- Run E2E/browser checks: `<fill in>`

## Completion Criteria

A task is complete only when:

- the requested behavior is implemented
- relevant checks pass or failures are clearly explained
- user-facing behavior is verified when applicable
- no unrelated changes were introduced
- the final response reports what changed and what was verified
```

### 规格层块

```markdown
## Spec Layer

For non-trivial feature, behavior, architecture, data, automation, or user-facing changes, create or update a written change artifact before implementation.

The change artifact should describe:

- why the change is needed
- what behavior changes
- important design decisions
- implementation tasks
- verification criteria

If a spec/change artifact already exists, use it as the source of truth. Do not create a separate competing plan unless explicitly requested.
```

### 执行纪律块

```markdown
## Agent Discipline

Use disciplined engineering workflow:

- clarify ambiguous requirements before implementation
- prefer test-first or TDD for features and bug fixes
- debug from root cause, not symptoms
- review diffs before calling work complete
- verify behavior with tests, browser checks, logs, screenshots, or reproducible commands

Do not claim completion without evidence.
```

### 专家审查块

```markdown
## Specialist Review

Use specialist review only when the project risk justifies it.

Recommended gates:

- product/scope review before large user-facing work
- engineering/design review before complex implementation
- code review after implementation
- QA/browser verification for critical user flows
- security review for auth, permissions, user data, payments, scraping, publishing, or third-party automation
- release review before production deployment

If a spec/change artifact exists, specialist review should improve that artifact, not replace it with a second plan.
```

### 外部操作安全块

```markdown
## External Action Safety

Treat networked and external actions as approval-required unless the user explicitly authorizes them.

Ask before:

- pushing commits
- opening or merging PRs
- deploying
- modifying production data
- posting or sending messages
- changing credentials
- running paid jobs
- operating real third-party accounts

Do not send private code, customer data, secrets, production logs, database exports, or credentials to untrusted agents, MCP servers, browser automation, or external services.

For high-risk flows, produce a local plan or report first.
```

### 工具底座块

```markdown
## Harness and Tooling Packs

If this project uses a broader AI tooling pack with skills, hooks, rules, MCP servers, or memory features:

- preserve existing project rules
- install only the components this project needs
- avoid duplicate rules from multiple packs
- document what was installed and why
- require maintainer approval before enabling hooks or external-action automation
```

### 完整示例：中型 Web App（标准工作流）

下面是一个中型 Web App（标准工作流 / Level 2）填好的 `AGENTS.md` 完整示例，组合了基础块、规格层块、执行纪律块和外部操作安全块，并填入真实命令，可直接参考：

```markdown
# AI Project Workflow

## Project Rules

Before changing code, inspect the existing project structure and follow local patterns.

Do not perform unrelated refactors, formatting churn, dependency upgrades, or broad cleanup unless explicitly requested.

If scope needs to expand, stop and explain why before continuing.

## Spec Layer

For non-trivial feature, behavior, architecture, data, automation, or user-facing changes, create or update a change artifact under `docs/changes/` before implementation.

If a change artifact already exists, use it as the source of truth. Do not create a separate competing plan unless explicitly requested.

## Agent Discipline

- clarify ambiguous requirements before implementation
- write tests before or alongside code for features and bug fixes
- debug from root cause, not symptoms
- review the diff before calling work complete
- do not claim completion without evidence

## Verification

Before completion, run the relevant checks and report the commands and results.

Project commands:

- Install dependencies: `pnpm install`
- Run tests: `pnpm test`
- Run lint/typecheck: `pnpm lint && pnpm typecheck`
- Build: `pnpm build`
- Run E2E/browser checks: `pnpm test:e2e`

## External Action Safety

Ask before pushing commits, opening or merging PRs, deploying, or modifying production data.

Do not send private code, customer data, secrets, production logs, database exports, or credentials to untrusted agents, MCP servers, browser automation, or external services.

## Completion Criteria

A task is complete only when:

- the requested behavior is implemented
- relevant checks pass or failures are clearly explained
- user-facing behavior is verified when applicable
- no unrelated changes were introduced
- the final response reports what changed and what was verified
```

---

## 11. 示例工作流

### 小改动

```text
读取项目规则
→ 做范围内修改
→ 运行相关测试或检查
→ 报告结果
```

### 标准功能

```text
评估改动大小
→ 非平凡变更创建或更新规格 artifact
→ 审查计划
→ 带测试实现
→ 验证
→ 总结
```

### 高风险产品变更

```text
创建或更新规格
→ 按需做产品/工程/安全审查
→ 更新任务
→ 带测试实现
→ 代码审查和 QA
→ 按规格验证
→ 获得批准后发布
```

### Bug 修复

```text
复现问题
→ 查根因
→ 写失败测试或最小复现
→ 修根因
→ 验证测试通过
→ 检查回归
```

---

## 12. 安装说明

工具安装方式会变化。开源文档中应优先链接上游官方安装说明，而不是把所有安装命令写死。

通用建议：

- 尽量把工作流工具安装在 agent/user 层
- 不要把工具内部文件 vendor 进每个仓库
- 仓库里只提交项目特定规则、规格和配置
- 团队未达成共识前，使用 optional/team mode，不要直接 required
- 不理解作用范围前，不要启用 hooks、MCP servers 或外部操作自动化

推荐接入顺序：

```text
1. 评估项目。
2. 选择工作流级别。
3. 添加或更新 AGENTS.md。
4. 只有需要时才初始化规格层。
5. 只有维护者批准后，才添加专家审查或重型工具底座。
6. 用一个小改动测试工作流是否顺畅。
```

---

## 13. 维护者合并清单

在把 agent 工作流接入仓库前，确认：

- [ ] 已记录项目风险评分。
- [ ] 已说明为什么选择该工作流级别。
- [ ] 已保留现有项目规则。
- [ ] 新规则足够短，AI 能真正遵守。
- [ ] 只加入项目需要的可选工具块。
- [ ] 外部操作需要明确批准。
- [ ] 验证命令已经补全。
- [ ] 已用一个小改动测试过工作流。

---

## 14. 推荐仓库文件

对开源项目，保持文件尽量少：

```text
AGENTS.md                   # AI agent 项目规则
CONTRIBUTING.md             # 可选：贡献指南、同步和验证规则
CHANGELOG.md                # 可选：项目变更记录
docs/agent-workflow.md       # 可选：给人看的工作流说明
docs/changes/                # 可选：轻量变更文档
openspec/                    # 可选：使用 OpenSpec 时再创建
```

除非团队确实使用，否则不要创建大量工具特定文件。

---

## 15. 可选工程规约参考目录

下面这些开源规约适合作为参考，但不应该默认进入主流程。它们不是安装项，也不是强制要求；只有当项目风格、风险和成熟度匹配时，才把对应规约写入 `AGENTS.md`、review checklist、设计文档或发布流程。

这些参考不是按 star 数排名，出现在表里也不等于无条件背书。采用前请确认来源是否适合你的场景、是否仍在维护或属于稳定历史资料、许可证是否兼容，以及它是否真的能降低当前项目风险。

| 场景 | 参考 | 适合使用时机 |
|---|---|---|
| Code Review | [google/eng-practices](https://github.com/google/eng-practices) | 团队需要统一代码审查标准、变更作者责任、review 质量。如项目已归档，应按稳定历史参考使用。 |
| 安全开发 | [OWASP/CheatSheetSeries](https://github.com/OWASP/CheatSheetSeries) | 涉及 auth、权限、输入校验、XSS、SQL 注入、文件上传、敏感数据。 |
| 架构决策 | [adr/madr](https://github.com/adr/madr) / [architecture-decision-record/architecture-decision-record](https://github.com/architecture-decision-record/architecture-decision-record) | 需要记录长期架构决策、权衡、替代方案和上下文。 |
| Commit 规范 | [conventional-commits/conventionalcommits.org](https://github.com/conventional-commits/conventionalcommits.org) | 需要规范 commit message、自动 changelog、release automation。 |
| 版本规范 | [semver/semver](https://github.com/semver/semver) | 开源库、SDK、CLI、API、插件需要清楚表达兼容性和破坏性变更。 |
| Changelog | [olivierlacan/keep-a-changelog](https://github.com/olivierlacan/keep-a-changelog) | 面向用户或开发者发布版本，需要维护可读变更记录。 |
| 供应链安全 | [ossf/scorecard](https://github.com/ossf/scorecard) | 开源项目需要检查安全健康度、CI、分支保护、依赖风险。 |
| SLSA | [slsa-framework/slsa](https://github.com/slsa-framework/slsa) | 成熟项目需要构建、发布、provenance 和供应链安全保证。 |
| API 设计 | [microsoft/api-guidelines](https://github.com/microsoft/api-guidelines) | REST API、平台 API、SDK API 需要一致的命名、错误、分页、兼容性规则。 |
| Spec-driven 参考 | [github/spec-kit](https://github.com/github/spec-kit) | 团队需要更正式的 spec-driven development 生命周期；不要和另一套规格层同时当主事实来源。 |

选择规则：

- **库/SDK/CLI**：优先 SemVer、Keep a Changelog、Conventional Commits。
- **Web App/SaaS**：优先 OWASP、Code Review、E2E/QA 规则。
- **API/平台服务**：优先 API Guidelines、ADR、SemVer。
- **高安全项目**：优先 OWASP、Scorecard、SLSA。
- **团队协作项目**：优先 Code Review、ADR、Commit 规范。
- **AI-heavy 项目**：优先规格层和执行纪律（见第 7、10 节）。
- **小项目**：不要引入目录；只保留最小 `AGENTS.md` 和测试命令。

---

## 16. 最终原则

最好的 AI 工作流，是能可靠防止项目真实失败模式的最小工作流。

需要长期记忆时，用规格。  
AI 会改代码时，用纪律。  
风险足够高时，用专家审查。  
团队真的需要时，再上重型工具底座。

---

## 17. 许可

本指南是工具中立的开放文档，欢迎自由使用、修改和分发。

- 文档正文采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)：可自由复制、改编和再分发，只需保留署名。
- 第 10 节的 `AGENTS.md` 模板和示例代码块视为公共领域（CC0）：可直接复制进任何项目，无需署名。
- 文中提到的第三方工具和参考各自遵循其自身许可，不在本指南许可范围内；使用前请查阅对应项目的 LICENSE。

如果把本指南放进代码仓库，建议在仓库根目录单独提供一份 `LICENSE` 文件。