Agents Markdown

当前版本：v0.2.0

这是什么？

痛点：AI Agent（Claude Code、Cursor、Copilot 等）没有持久记忆，每次对话都是新开始。它不知道你的项目用什么技术栈、有什么约束、该怎么做事。

方案：通过一套 prompt 模板，引导 Agent 自动生成项目专属的协作文档。之后 Agent 进入项目时，读取这些文档就能快速上手。

本质：把「你脑子里的项目知识」外化成「Agent 能读懂的文档」。

安装与使用

npx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/agents-markdown.json

yarn dlx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/agents-markdown.json

pnpx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/agents-markdown.json

bunx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/agents-markdown.json

安装后，在 Agent 对话中输入：

请从 .ai-coding/ENTRY.md 开始，按其中流程初始化这个项目的 AI Coding 脚手架。

Agent 会通过问答收集信息，自动生成以下文件：

生成的文件	作用
`AGENTS.md`	唯一协作规范入口
`CLAUDE.md`	Claude Code 兼容跳转壳（指向 AGENTS.md）
`docs/WORKFLOW_TEMPLATES.md`	工作流 SOP，Agent 执行任务时参考
`docs/PROJECT_STATE_TEMPLATE.md`	PROJECT_STATE 模板
`docs/REVIEW_TEMPLATES.md`	评审标准，Agent 自检用
`docs/ARCHITECTURE.md`	项目架构详解
`PROJECT_STATE.md`	任务状态记录（执行任务时自动创建）

安装包同时会下发 Codex 多角色配置与技能：

安装到本地的文件	作用
`~/.codex/config.toml`	开启 `multi_agent` 并注册 `ac-*` agents
`~/.codex/agents/ac-agent-*.toml`	planner / executor / reviewer 角色配置
`~/.codex/skills/ac-*/`	`ac-plan`、`ac-execute`、`ac-review` 技能与 UI 元数据

初始化流程

.ai-coding/ENTRY.md        → 入口
    ↓
INIT_DIALOGUE.md           → 问答收集信息 → 生成 AGENTS.md + CLAUDE.md（跳转壳）
    ↓
INIT_WORKFLOW.md           → 选择工作流类型 → 生成 WORKFLOW_TEMPLATES.md + PROJECT_STATE_TEMPLATE.md
    ↓
INIT_REVIEW.md             → 确认评审标准 → 生成 REVIEW_TEMPLATES.md
    ↓
INIT_ARCHITECTURE.md       → 扫描项目 → 生成 ARCHITECTURE.md
    ↓
POST_INIT.md               → 收尾：更新 .gitignore，提示提交

设计原则

原则	体现
低感知	问答用编号选择，减少打字
可定制	工作流类型可选，评审项可扩展
自动化	评审是 Agent 自检，用户只看结论
不污染项目	`.ai-coding/` 加入 .gitignore，模板不入库

0.2.0 新增策略

引入条件式多角色路由（通用风险评分制）：

默认 single
0-3：single
4-6：single + reviewer
>=7：planner → executor → reviewer

引入执行冻结机制：

PLAN_FROZEN 控制是否允许执行
CURRENT_ROLE 记录当前角色
执行中新增设计必须解冻并回 planner

Commit Policy 固定：

仅在用户明确要求时允许 git commit
严禁默认执行 git push
Co-Authored-By: <llm-model> 使用动态模型名
默认不提交 PROJECT_STATE.md（除非跨环境同步或用户明确要求）

PROJECT_STATE.md 升级为“2 头部字段 + 9 个接力区块”：

PLAN_FROZEN: true|false
CURRENT_ROLE: planner|executor|reviewer|single
目标
下一步 Top 3
阻塞项
关键决策索引（最近 3 条）
关键决策日志（全量追加）
验收证据（Evidence）
未验证清单（Gaps）
提交计划
Execution Contract

PROJECT_STATE 实践经验

适用范围

本实践适用于：单 Agent + 条件式多角色的 AI Coding 协作场景，主要目标是解决无持久记忆 Agent 在多轮对话中「状态丢失 / 执行不连续 / 执行期重新设计」的问题。

当前设计已在 Cursor / Claude Code 等环境中验证稳定；默认保持 single，仅在风险升高时升级角色。

背景问题

在早期版本中，我们已明确要求 workflow 模式下维护 PROJECT_STATE.md，但在实际使用中发现：

Agent 会在轻量任务、连续执行阶段偶发性忽略状态维护
规则存在，但未进入 Agent 的执行优先级

问题不在于规则不清，而在于规则不具备"强制执行条件"。

核心经验结论

对 LLM 来说：规范 ≠ 必须执行的步骤。

只有"影响流程是否成立"的规则，才会被稳定遵守。

关键做法（v0.1.2）

围绕 PROJECT_STATE.md，我们做了三点调整：

硬门禁
- 未完成 PROJECT_STATE 检查 / 更新 → workflow 视为未启动
状态锚点
- workflow 模式下，每轮输出必须包含可见状态声明：
```
[STATE] PROJECT_STATE.md：todo 3 → 2，阶段：📐设计
```
封死逃逸路径
- 明确规定：即使是轻量任务，也不得跳过状态维护

这些调整将状态管理从「行为规范」升级为「流程成立条件」。

迭代过程

版本	特点
v0.1.0–0.1.1	状态作为规范，偶发失效
v0.1.2	硬门禁 + 状态锚点，稳定性显著提升
v0.1.3	最低输出频率 + 模式回切，处理边界情况
v0.1.4	入口统一 + 接力面板 + Commit Policy 固定化
v0.2.0	通用多角色路由 + PLAN_FROZEN + Execution Contract

关键转折点不是规则更详细，而是规则是否具备失败判定。

验收标准

✅ workflow 模式下 [STATE] 输出出现率接近 100%
✅ 轻量任务与连续执行阶段不再"无状态"
✅ Agent 开始主动维护状态，而非被提醒后补救

可复用原则

想让 Agent 稳定执行某个行为：

把它设为流程门禁
要求每轮可见产物
明确禁止跳过的场景

仅靠"写清楚规则"，不足以约束 LLM 行为。

版本管理

检查当前版本

查看 AGENTS.md 顶部注释：

<!-- ai-coding-scaffold: v0.2.0 -->

更新

重新下载覆盖 .ai-coding/ 目录
让 Agent 执行升级：

请读取 .ai-coding/UPGRADE.md 和 .ai-coding/CHANGELOG.md，帮我升级 AGENTS.md 到最新版本。

Agents Markdown

目录