SSP AI Coding Registry

当前版本：v0.2.7

这是什么？

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

方案：通过一套 prompt 模板，把项目协作规则、工作流入口和状态管理方式沉淀成文档，让 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
`docs/PROJECT_STATE_TEMPLATE.md`	`PROJECT_STATE.md` 模板
`docs/REVIEW_TEMPLATES.md`	自检与评审标准
`docs/ARCHITECTURE.md`	项目架构说明
`PROJECT_STATE.md`	执行任务时自动创建、默认加入 `.gitignore` 的状态面板

安装包也会自动带上 ac-skills 的多角色能力：

安装到本地的文件	作用
`~/.codex/config.toml`	开启 `multi_agent` 并注册 `ac-*` agents
`~/.codex/agents/ac-agent-*.toml`	core triad + specialized / lite agents 的角色配置
`~/.agents/skills/ac-memory/`	`PROJECT_STATE.md` 的本地记忆与门禁管理
`~/.agents/skills/ac-workflow/`	workflow 编排入口
`~/.agents/skills/ac-plan/` `ac-execute/` `ac-review/`	角色化执行与交接

其中 Codex 的项目级 skills 使用 ~/.agents/skills/ 扫描；~/.codex/* 继续承载 Codex 自身配置与 agent 定义。

当前 agents-markdown 会通过 registry 依赖自动带上 ac-skills，所以安装脚手架时会同时落下 workflow 所需的能力包。

当前 workflow 可以理解为三层能力：

ac-memory：负责 PROJECT_STATE.md 的本地记忆、结构校验和 [STATE] 门禁
ac-workflow：负责 workflow 入口、阶段推进、continue 恢复与强制收尾
ac-plan / ac-execute / ac-review：负责核心 triad 的角色化执行与交接
ac-frontend-integration / ac-debug-investigator / ac-pr-review：负责 specialized tasks
ac-explorer-lite / ac-chore-editor：负责 spark 驱动的轻量探索与 chore/edit

在 registry 配置里，这里使用的是 public registry 自引用写法：

{
  "registryDependencies": ["<PUBLIC_REGISTRY_WEBSITE>/r/ac-skills.json"]
}

这样做的好处是，agents-markdown 被其它项目消费时，不依赖当前仓库的本地短名解析，也能稳定拉取 ac-skills。

初始化流程

.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（含 PROJECT_STATE.md），提示提交

0.2.x 结构演进

0.2.x 的整体方向不是继续把规则堆进 AGENTS.md，而是把稳定、可复用、值得反复调用的部分逐步拆成显式能力。

版本	变化
`0.2.0`	引入通用多角色路由、`PLAN_FROZEN` 和 `Execution Contract`
`0.2.1`	项目级 skills 从 `.codex/skills/` 迁移到 `~/.agents/skills/`
`0.2.2`	将 `ac-` 与 `ac-agent-` 拆出到独立的 `ac-skills`
`0.2.3`	新增 `ac-memory`，把 `PROJECT_STATE` 基础管理收口为独立能力
`0.2.4`	新增 `ac-task`，把 workflow 编排从文案规则收口到入口 skill
`0.2.5`	将入口 skill 正式更名为 `ac-workflow`，继续简化 `AGENTS.md`
`0.2.6`	升级改为 Agent 读取 `UPGRADE.md` + `CHANGELOG.md` 执行 checklist
`0.2.7`	`PROJECT_STATE.md` 默认加入 `.gitignore`，并补强 Codex agent / model 策略说明

PROJECT_STATE 方法论

它解决什么问题

PROJECT_STATE.md 主要解决三类问题：

多轮对话里状态丢失
连续执行时上下文断裂
执行中临时改方案，导致计划和结果脱节

核心做法

这套方法最后收敛成三件事：

把状态维护设成 workflow 成立的门禁
要求每轮都产出可见的 [STATE] 锚点
用 PLAN_FROZEN、CURRENT_ROLE 和 Execution Contract 约束执行期行为

为什么有效

关键不在于规则写得更长，而在于 Agent 会把这些规则当成流程前提：

不更新状态，workflow 就不成立
没有可见锚点，用户和 Agent 都无法确认当前阶段
没有冻结与 Contract，执行期就容易重新设计

也因此，PROJECT_STATE.md 从“记笔记”变成了“驱动执行的状态面板”。

适用边界

这套方法最适合：

单 Agent + 条件式多角色协作
需要跨轮继续的开发任务
需要把计划、执行、验收串成闭环的任务

它不等同于通用知识库，也不替代长期文档系统；当前重点仍然是任务级状态接力。

可复用原则

如果你想让 Agent 稳定执行某个行为，通常可以复用这几条原则：

把它设为流程门禁
要求每轮产出可见结果
明确哪些场景禁止跳过
当某部分已经稳定且可复用时，把它从大 prompt 中拆成显式能力

版本管理

查看 AGENTS.md 顶部注释即可检查当前版本：

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

升级时，先覆盖新版 .ai-coding/，再直接让 Agent 执行：

请读取 .ai-coding/UPGRADE.md 和 .ai-coding/CHANGELOG.md，
识别当前版本并按顺序执行到最新版本的 Upgrade Checklist。
升级 AGENTS.md 时，请主动删除旧版本遗留、重复解释和已被模板替代的脚手架文案，
但保留项目自定义约束。

Agents Markdown