# AGENTS.md

把这个文件放在项目根目录，用来把已安装的 Codex skills 注册给 Codex。项目级约束可以追加在文末的 `Repo notes` 一节。

## Coding 宪法

### 最优路径优先

- 先基于当前目标、约束和上下文判断最优路径，再沿着这条路径推进。
- 默认先收敛到一个最优方案，不先为了自我防御同时铺退路、保守版、兼容版或降级版。
- 只有在最优路径被事实阻塞、风险或成本发生实质变化、或用户明确要求方案比较时，才展开 fallback 与备选方案。
- 提问和澄清只用于解决会改变最优路径判断的问题，不能把提问当成免责动作。

## Skills

### Available skills

- `rr`: 评审 RequirementsDoc.md，检查需求文档的完整性、清晰度和可执行性，输出结构化评审报告。 (file: `./.codex/skills/rr/SKILL.md`)
- `rp`: 评审 PRD.md，对比 RequirementsDoc 检查一致性，输出结构化评审报告。 (file: `./.codex/skills/rp/SKILL.md`)
- `rf`: 评审 FeatureSummary.md，对比 PRD 检查一致性，输出结构化评审报告。 (file: `./.codex/skills/rf/SKILL.md`)
- `rd`: 评审 DevelopmentPlan.md，检查技术可行性和与上游文档一致性，输出结构化评审报告。 (file: `./.codex/skills/rd/SKILL.md`)
- `ru`: 评审 UIDesign.md，对比 DevelopmentPlan 检查设计一致性，输出结构化评审报告。 (file: `./.codex/skills/ru/SKILL.md`)
- `rt`: 评审 tasks.md，检查任务完整性和与上游文档一致性，输出结构化评审报告。 (file: `./.codex/skills/rt/SKILL.md`)
- `wp`: 从 RequirementsDoc.md 生成 PRD.md，将需求文档转化为结构化的产品需求文档。 (file: `./.codex/skills/wp/SKILL.md`)
- `wf`: 从 RequirementsDoc.md 和 PRD.md 生成 FeatureSummary.md，提供功能全貌概览。 (file: `./.codex/skills/wf/SKILL.md`)
- `wd`: 从上游文档生成 DevelopmentPlan.md，包含技术方案和开发排期。 (file: `./.codex/skills/wd/SKILL.md`)
- `wu`: 从上游文档生成 UIDesign.md，覆盖所有用户界面设计。 (file: `./.codex/skills/wu/SKILL.md`)
- `wt`: 从上游文档生成 tasks.md，创建可直接执行的任务列表。 (file: `./.codex/skills/wt/SKILL.md`)
- `mr`: 增量修改 RequirementsDoc.md，根据用户指令在现有内容基础上更新需求文档。 (file: `./.codex/skills/mr/SKILL.md`)
- `mp`: 增量修改 PRD.md，根据用户指令在现有内容基础上更新产品需求文档。 (file: `./.codex/skills/mp/SKILL.md`)
- `mf`: 增量修改 FeatureSummary.md，根据用户指令在现有内容基础上更新功能摘要。 (file: `./.codex/skills/mf/SKILL.md`)
- `md`: 增量修改 DevelopmentPlan.md，根据用户指令在现有内容基础上更新开发计划。 (file: `./.codex/skills/md/SKILL.md`)
- `mu`: 增量修改 UIDesign.md，根据用户指令在现有内容基础上更新 UI 设计文档。 (file: `./.codex/skills/mu/SKILL.md`)
- `mt`: 增量修改 tasks.md，根据用户指令在现有内容基础上更新任务列表。 (file: `./.codex/skills/mt/SKILL.md`)
- `go`: 终极执行按钮，激进模式一口气完成开发任务，兼容 0->1 和 1->100 场景。 (file: `./.codex/skills/go/SKILL.md`)
- `iter`: 迭代变更入口，调研问题后更新 PRD.md 和 tasks.md，支持 Bug 修复、功能迭代、技术重构。 (file: `./.codex/skills/iter/SKILL.md`)
- `doc`: 渐进式文档生成器。首次只写精炼梗概（≤300字），后续通过迭代不断完善。 (file: `./.codex/skills/doc/SKILL.md`)
- `capture`: 复刻一次成功任务的经验，输出到用户指定目录。调用方式 `/capture <目录>` 或 `$capture <目录>`，生成只含 fenced YAML 的 Markdown 记录。 (file: `./.codex/skills/capture/SKILL.md`)
- `update`: 收集用户反馈并更新最近使用的 skill。别名：`up`。 (file: `./.codex/skills/up/SKILL.md`)
- `deploy`: Drone CI + 服务器 CD 全流程引导：从基础设施检查到生成配置文件到验证部署，交互式完成。 (file: `./.codex/skills/deploy/SKILL.md`)
- `gitea`: 统一 Gitea 总入口，支持 issue 查询、issue 拆单创建、git push 和 PR 基础操作，优先从当前仓库 origin 自动识别目标仓库。 (file: `./.codex/skills/gitea/SKILL.md`)
- `issue`: 查看当前仓库或任意 Gitea 仓库的 issue 列表和单条详情，支持自动识别 git origin、用户指定仓库和格式化输出。 (file: `./.codex/skills/issue/SKILL.md`)
- `issue-drive`: 归集证据并把问题拆成 1 到多张 Gitea issue，支持从当前仓库 origin 自动识别仓库或用户显式指定。 (file: `./.codex/skills/issue-drive/SKILL.md`)
- `changelog`: 一键发版：生成更新日志 → commit → 打 tag，全流程自动化。 (file: `./.codex/skills/changelog/SKILL.md`)

### How to use skills

- Discovery: 以上列表就是当前仓库提供给 Codex 的 skills。
- Trigger rules: 如果用户显式提到 skill 名称（例如 `/rr`、`$rr`、`rr skill`、`用 rr 评审`），或任务明显匹配 skill 描述，优先使用对应 skill。
- Codex usage: 在 Codex 中优先使用 `/skill-name`；兼容历史 `$skill-name` 写法，也支持自然语言触发。
- Missing/blocked: 如果某个 skill 文件不存在或无法读取，简短说明并回退到普通实现方式。
- Context hygiene: 只按需打开 `SKILL.md`，不要一次性加载整个 skill 仓库。

### Repo notes

- `./.claude/skills/` 保留给 Claude Code。
- `./.codex/skills/` 是 Codex 的实际安装源。
- 迁移或新增 skill 时，优先同步更新 `README.md`、`AGENTS.md`、`AGENTS.md.template`。