代码可以很快生成，工程结果仍然需要被控制、验证和接住。
super-dev 是一套给强 Coding Agent 使用的、项目原生的研发 Harness。它面向全栈、多模块和多代码仓库的真实研发，把上下文、工作区、权限、完成定义、验证证据和知识沉淀整理成一组可执行的工程合同。个人可以把它当作协作习惯，团队也可以用它统一最低交付标准；本仓库来自具体项目中的反复实践，只提供一套可裁剪的参考，不主张它是唯一做法。
下面是脱敏后的推荐轮廓。目录名可以按项目调整，重要的是不要把规则、任务状态、长期知识和原始证据混在一起。
product-workspace/
├── AGENTS.md -- 高频、必须遵守的项目规则与文档入口
├── docs/
│ ├── codemap/
│ │ └── project-profile.md -- 仓库拓扑、架构、交付与验证模型
│ ├── specs/ -- 活跃任务的目标、边界、Done Contract 与证据
│ │ └── YYYY-MM-DD_author_topic/
│ │ ├── feature.md -- 当前任务真相源与恢复点
│ │ └── test-report.md -- 按需记录验证过程和结论
│ ├── issues/ -- 从主任务拆出的旁支问题与团队 backlog
│ ├── archived/ -- 已关闭 spec / issue 的冷归档
│ ├── knowledge-sources/ -- Wiki 的只读原始材料，保留来源
│ └── wiki/ -- LLM 维护、可交叉引用的项目知识库
│ ├── AGENTS.md -- Wiki schema、分区和维护规则
│ ├── README.md -- 人类阅读入口
│ ├── index.md -- 全局内容索引
│ ├── log.md -- ingest / update / lint 时间线
│ ├── inbox/ -- 待编译材料，不直接视为项目事实
│ └── 00-start-here/ -- 知识分区示例，按领域扩展
├── .worktrees/ -- 可选的本地任务 worktree，通常不提交
└── repos/
├── api-service/ -- 后端或服务仓库
└── web-app/ -- 前端或客户端仓库
上图使用 AGENTS.md，是因为作者当前主要使用 Codex。若使用 Claude Code CLI，应将项目根目录和 Wiki 内的入口文件改为 CLAUDE.md；两者职责相同，不需要同时维护两份。使用其他 Agent 时，映射到它原生支持的项目指令文件即可。本文后续以 AGENTS.md 代称这类入口。
单仓项目不需要为了形式照搬 repos/；已有成熟目录也无需迁移。super-dev 关心的是信息职责和验证边界，而不是固定文件名。
强 Agent 已经能读代码、跨文件修改、运行工具、排障和交付。真正容易失控的地方，往往发生在代码生成前后：
| 工程问题 | super-dev 的处理方式 |
|---|---|
| 任务越做越偏，长会话后目标漂移 | Restate First、单一当前目标、可恢复 Spec |
| dirty checkout 或并行任务互相污染 | 基线检查、显式文件边界、Worktree Contract |
| 前后端或微服务跨仓协作失去主线 | Project Registry、逐仓切换、独立基线与证据 |
| “改完了”却没人说得清什么叫完成 | 先写 Done Contract，再选择验证方式 |
| 构建、发布、运行态和业务结果被混为一谈 | Evidence Contract + 权威系统回读 |
| Agent 擅自扩大权限或触发外部写操作 | Scoped Authority + 风险 checkpoint |
| 经验只留在聊天里，下次重新探索 | Reverse Sync + llm-wiki 知识编译 |
| 通用协议被某家公司或某套工具绑死 | 公共核心与项目私有 adapter 分离 |
| Skill | 负责什么 | 典型产物 |
|---|---|---|
super-dev |
控制一次研发任务如何安全、可验证、可恢复地推进 | Spec、Done Contract、worktree 状态、验证证据、收尾记录 |
llm-wiki |
把已经验证、值得复用的项目知识编译成长期知识库 | Wiki 页面、索引、交叉引用、来源映射、维护日志 |
知识复利是 super-dev 体系的核心能力之一，但不是每个编码请求都需要加载完整 Wiki 流程。因此 llm-wiki 作为独立 companion skill 发布：可以单独安装，也可以与 super-dev 配合；主 skill 不会因为它未安装而阻塞普通研发任务。
处理研发任务时：
本次任务使用 $super-dev。
先复述目标、范围、假设和 Done Contract。
检查仓库、分支与 dirty state，选择合适的任务深度。
普通范围内的本地工作自主推进；新风险、外部写操作或扩范围前 checkpoint。
最后用当前证据说明实现、交付、运行态和用户结果分别到了哪一步。
需要初始化或维护项目知识库时：
使用 $llm-wiki 初始化 docs/wiki，并把 docs/knowledge-sources 设为只读来源层。
先定义 Wiki schema、分区和索引，再 ingest；不要把临时任务状态或私有记忆写进项目知识库。
也可以在项目指令文件中加入一条短规则：
非平凡编码、排障、重构、验证和交付任务默认使用 super-dev。
稳定、已验证且适合仓库共享的知识，按项目约定交给 llm-wiki 维护。
项目自身的安全、提交和验证规则优先。
读项目入口
-> 复述目标、边界、授权和 Done Contract
-> 选择 zero / fast / standard / deep
-> 建立最小可恢复 Spec
-> 检查基线并隔离实现
-> 在新风险或外部写操作前 checkpoint
-> 实现并逐级验证
-> 从权威系统回读目标状态
-> 收尾 Spec，记录偏差、残余风险和恢复点
-> 只同步稳定、可复用、适合该仓库的知识
人负责目标、边界、高影响授权和最终验收；Agent 在这个边界内负责探索、实现、迭代和相称验证。普通本地工作不制造审批仪式，真正跨越权限或影响共享状态时才停下来确认。
项目指令文件往往会在每次任务开始时被读取。它越长，真正必须遵守的规则越容易被背景材料淹没；易变坐标和大段架构说明也更容易过期。
建议只在 AGENTS.md 或 CLAUDE.md 中放：
- 语言、提交、安全和分支等高频硬规则；
- 仓库根、Spec 目录、worktree 策略和隐私边界；
- 必跑的构建、测试、验证入口；
project-profile、Wiki、私有 runbook 等文档的索引；- 项目特有且每次任务都必须知道的少量例外。
其余内容按职责拆开：
| 位置 | 适合放什么 |
|---|---|
docs/codemap/project-profile.md |
项目类型、仓库 Registry、模块职责、依赖、交付模型、验证阶梯和完成门禁 |
docs/specs/ |
当前任务的目标、范围、决策、进度、证据、发布状态和恢复点 |
docs/issues/ |
不阻塞当前主线、但值得后续处理的问题 |
docs/archived/ |
已结束任务的历史材料；默认不装入活跃上下文 |
docs/wiki/ |
跨任务复用的架构、领域概念、判断方法、故障经验和关系图 |
| 私有 adapter / runbook | 环境坐标、部署命令、日志和数据查询等易变或敏感内容 |
Project Profile 比项目指令文件更详细，但仍应尽量稳定。它回答“这个项目如何交付、什么证据才算完成”；具体 token、内部地址、生产数据和个人路径不属于公开协议。
super-dev 不要求每个单行修改都创建 worktree。zero 或简单 fast 任务在干净工作区中可以直接完成；standard、deep 或存在并行改动时，优先用专属 worktree。
进入实现前至少确认：当前仓库、基线 commit、dirty / untracked 文件、task branch、集成目标、交付目标和 worktree 保留策略。未经授权，不 reset、clean、stash 或吸收无关改动；提交时只暂存明确文件。
跨仓任务先建立一个小型 Project Registry，说明每个仓库的职责和本轮修改范围。一次只进入当前需要的仓库；每个仓库分别维护基线、分支、测试和交付证据，不能拿后端的成功测试替代前端验收。
完成是一项需要证据支持的声明。super-dev 将常见证据分成五级：
| 层级 | 可以证明什么 |
|---|---|
| E0 | 源码、diff、schema 和静态约束 |
| E1 | 单测、lint、类型检查和构建完整性 |
| E2 | 组件之间的集成、契约或消费方兼容性 |
| E3 | 指定 revision 在目标环境中的真实行为 |
| E4 | 用户可见或业务验收结果 |
低层证据不能替代高层结论：构建成功不是部署成功，部署记录不是运行正确，一次响应成功也不自动代表完整业务结果。Done Contract 应在实现前说明每项结果由什么证明；共享或外部写操作后，还要从权威系统回读准确目标和 revision。
llm-wiki 把知识分成三层：
Raw Sources -> 不改写的原始材料和证据
Wiki -> LLM 维护、供人和 Agent 阅读的 Markdown 知识网络
Schema -> Wiki 内的 AGENTS.md / CLAUDE.md，约束分区、格式和维护动作
Agent 可以先把材料放进 inbox/，再通过 ingest 提炼页面、补索引、交叉引用和来源；Query 回答要指向具体 Wiki 页面；Lint 检查断链、孤立页、过期结论和积压材料。
Wiki 只接收已经验证、跨任务值得复用、且适合该仓库共享的知识。临时 Todo、未确认推断、原始生产日志、私有 handoff、用户偏好和系统记忆不能因为“以后可能有用”就直接进入 Wiki。
公共核心不绑定 Git 平台、CI、部署系统、日志平台、数据库或云厂商。项目可以提供私有 adapter，负责版本管理、构建、部署、接口、UI、日志、Trace、数据、配置和消息等能力。
每个 adapter 都应声明读写操作、目标坐标、鉴权边界、checkpoint、证据格式、权威回读和恢复方式。详见 Extension Contract。
GitHub 在这里仅用于公开托管和分发；super-dev 本身不依赖 GitHub，也没有提供可直接套用的 GitHub 提交、评审或发布集成。作者当前的实践主要发生在内网研发环境，代码提交与评审、CI / 构建 / 部署、真实环境测试，以及日志、Trace、数据和配置回读，都依赖项目自己的系统、权限与证据源。
因此，super-dev 不是安装后就能跨环境直接运行的工具。引入新项目时，需要在 Project Profile 和私有 adapter 中映射实际的仓库与分支模型、评审和交付流程、鉴权边界、测试入口、权威回读与回滚方式。公共协议约束“哪些事实需要成立、用什么级别的证据声明完成”，具体命令和平台配套由实际使用场景负责。
安装核心研发 skill：
npx skills add brantshin/super-dev \
--skill super-dev \
--global \
--agent codex \
--yes按需安装知识库 companion：
npx skills add brantshin/super-dev \
--skill llm-wiki \
--global \
--agent codex \
--yes将 --agent codex 换成 --agent claude-code 可安装到 Claude Code。也可以手动复制 skills/super-dev 和 skills/llm-wiki 到目标 Agent 的 skill 目录。
当前公开目录页：Agent Skill Hub · skills.sh。第三方索引可能晚于 GitHub 最新 revision。
super-dev/
├── README.md -- 默认中文说明
├── README.en.md -- English
├── README.zh-CN.md -- 旧中文链接兼容入口
├── CONTRIBUTING.md
├── SECURITY.md
├── LICENSE
└── skills/
├── super-dev/ -- 研发控制协议
│ ├── SKILL.md
│ ├── agents/openai.yaml
│ └── references/ -- Spec、Evidence、Worktree 等合同
└── llm-wiki/ -- 项目知识库 companion
├── SKILL.md
├── agents/openai.yaml
└── references/ -- 初始化、知识拓扑与维护合同
仓库不包含真实基础设施 adapter、生产样例、凭据或安装脚本。
公开内容不得包含凭据、内部域名、基础设施坐标、个人路径、私有消息、生产 payload、日志、Trace、截图、数据库记录、真实任务历史或用户记忆。示例应使用合成名称和数据；项目私有坐标留在适合的私有文档中。
super-dev 的具体形态来自自己的项目实践，也明显受这些项目和方法启发：
- sdd-riper：轻量控制面、Spec、checkpoint、证据与反向同步；
- Superpowers：可组合 skill、worktree 和验证纪律；
- Karpathy's LLM Wiki：由 LLM 持续编译和维护的知识库模式；
- mattpocock/skills：super-dev 在实际使用中通常会与其中的
grill-me、handoff等 skill 配合；前者用于在方案前暴露假设和取舍，后者用于长任务、换会话或交接时保留可恢复上下文。
这里是学习后的工程化重组，不是上述项目的再实现，也不代表其作者。欢迎把它当作参考，按自己的项目规模、风险和协作方式删改。
贡献应加强通用工程合同，而不是把某个组织的运行态知识塞进公共核心。提交前请阅读 CONTRIBUTING.md。疑似凭据或隐私泄漏请按 SECURITY.md 私下报告，不要创建公开 Issue。
MIT，详见 LICENSE。