Codex Agent Project Template

一个面向 Codex 的流程治理模板，用来把 agent 约束成可规划、可追踪、可恢复、可交接的工程执行系统，而不是一次性代码生成器。

初始化

git init
git add .
git commit -m "init codex agent template"

默认不要求你先手填一堆文档，也不要求你复制长提示词。直接像平时用 cc 那样说人话就行，模板会在后台自动判断是新需求、恢复还是 review。

最简单用法

接管这个仓库，按模板推进：做一个用户登录功能。

从模板开新项目

从 codex-agent-template 开一个新项目：ticket-system

默认会做这些事：

• 复制当前模板到新目录
• 不复制模板仓库自己的 .git
• 初始化一个新的 git 仓库
• 创建初始提交
• 把新项目切到干净的初始治理状态
• 然后在新项目里继续接管和推进

如果你不写路径，默认会放到当前模板仓库的同级目录，例如 D:\Code\ticket-system。

最小输入示例

做一个用户登录功能

继续

review

把这个需求拆成任务

从模板开一个新项目：ticket-system

默认行为

• 你直接描述一个需求，agent 默认按新任务处理
• 你说“继续”，agent 默认按恢复流程处理
• 你说“review”或“检查一下”，agent 默认按 review / QA 处理
• 你说“从模板开一个新项目”，agent 默认复制模板、初始化新仓库、初始提交并切到新项目继续
• 如果 PROJECT_PROFILE.md 还是空的，agent 会先自动扫描仓库并补草稿
• 只有在关键命令、环境或业务决策无法安全推断时，agent 才会追问

显式说法

如果你想更稳，也可以用这些短句：

继续当前任务

review 当前改动

按模板启动一个新需求：<需求内容>

从模板开一个新项目：<项目名>

模板内容

• .codex/skills/: 可复用流程技能
• .codex/agents/: 角色定义
• AGENTS.md: 全局行为约束、角色边界、默认决策规则
• WORKFLOW.md: 状态机、阶段输入输出、准入与退出条件
• PROJECT_PROFILE.md: 与具体仓库绑定的命令、路径、环境、验证入口
• STATE.md: 当前最小可恢复上下文
• TASKS.md: 严格任务板，唯一任务事实源
• SPEC.md: 需求规格模板
• PLANS.md: 分阶段交付计划模板
• DECISIONS.md: 技术与产品决策日志
• RISKS.md: 风险登记
• HANDOFF.md: 交接模板
• FAILURES.md: 失败与阻塞记录
• ROLLBACK.md: 回滚预案
• EVALS.md / SCORECARD.md: 评估与质量打分

后台节奏

1. requirement-plan
2. technical-design
3. task-split
4. task-executor or build-current-phase
5. change-review
6. quality-gate
7. handoff-update

使用原则

• TASKS.md 是任务事实源，TODO.md 只作为可选草稿区。
• STATE.md 必须能让陌生 agent 在中断后恢复执行。
• PROJECT_PROFILE.md 是唯一允许写入项目特定命令和环境假设的地方，但允许 agent 先自动生成草稿。
• 如果需求、设计或验证信息缺失，先补文档，再决定是否继续执行。
• 如果 workflow 没有进入 BUILDING，默认不应该开始编码。
• 如果用户要求从模板创建新项目，优先走自动复制 + 新仓库初始化，而不是要求用户自己手动处理 git。