diff --git a/README.en.md b/README.en.md index 1132173..d29008b 100644 --- a/README.en.md +++ b/README.en.md @@ -102,6 +102,14 @@ Claim exactly one unowned task before starting work. | [CHANGELOG.md](CHANGELOG.md) | Release and milestone delivery history | | [SELFCHECK.md](SELFCHECK.md) | Machine-readable self-audit and anti-forgetting protocol for agents | +### Standard Skill + +| Skill | Purpose | +|---|---| +| [skills/kof](skills/kof/SKILL.md) | Standard kick-off flow: resume / reload / explicit-task modes, plus the per-task loop, closeout gates, and hand-off heuristics | + +Install: copy to `.claude/skills/kof/SKILL.md` in your project, replace the `{placeholders}` with your project's real values, and keep appending the traps you hit to the "project traps" section. Usage: `/kof` (resume), `/kof c` (reload after /clear), `/kof M3-T2` (explicit task). + ### Multi-Agent Native - `.vibe/project.json`: persistent project state and scheduling topology. diff --git a/README.md b/README.md index e16f103..bbe7cba 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,14 @@ flowchart LR | [CHANGELOG.md](CHANGELOG.md) | 版本与里程碑交付记录 | | [SELFCHECK.md](SELFCHECK.md) | 面向大模型的机读自查与防遗忘协议 | +### 标准 Skill + +| Skill | 作用 | +|---|---| +| [skills/kof](skills/kof/SKILL.md) | 标准开工流程(kick-off):续接 / 重载 / 指定任务三模式,含逐任务循环、收尾门禁与交接判据 | + +安装:复制到项目的 `.claude/skills/kof/SKILL.md`,把 `{占位}` 换成本项目实际值,并持续把踩过的坑追加进「项目坑位」一节。用法:`/kof`(续接)、`/kof c`(/clear 后重载)、`/kof M3-T2`(指定任务)。 + ### Multi-Agent Native - `.vibe/project.json`:持久化项目状态与调度拓扑。 diff --git a/skills/kof/SKILL.md b/skills/kof/SKILL.md new file mode 100644 index 0000000..0c7e275 --- /dev/null +++ b/skills/kof/SKILL.md @@ -0,0 +1,143 @@ +--- +name: kof +description: 标准开工流程(kick-off),三种模式。/kof=续接(同会话继续当前任务,不重读规则,最高频);/kof c=重载(记法:clear 后用——完整加载规则并自动定位最早未完成任务);/kof M3-T2 或 M3-T2..T4=指定任务(支持单个/批量/区间)。可附一句仓库外的时效说明(如并发会话情况)。配套 Vibe Coding 正式项目工作手册。 +--- + +# kof · 标准开工流程 + +> 本 skill 是**手册纪律的执行入口**:它不替代 PRD / PLAN / DECISIONS / CLAUDE.md,冲突时一律以仓库文档为准(AGENTS.md > CLAUDE.md > 本 skill)。 +> 安装:复制到项目的 `.claude/skills/kof/SKILL.md`,把 `{占位}` 换成本项目实际值,删掉不适用的行,并把「项目坑位」补成本项目真实踩过的坑。 + +## 模式判定(看参数第一个词) + +| 参数 | 模式 | 流程 | +|---|---|---| +| (无参数) | **一 · 续接**(最高频,故为默认) | 只走【续接流程】 | +| `c`(记法:**c**lear 后用;或 `reload`/`重载`) | **二 · 重载** | 走完整流程:定位 → 读 → 自查 → 执行 | +| 任务号(一个或多个,或区间) | **三 · 指定** | 跳过定位,走完整流程的读 → 自查 → 执行 | + +--- + +## 模式一 · 续接(无参数默认,同会话继续,轻量) + +前提:本会话上下文里**已有进行中的任务**(规则和任务描述都读过了)。此模式**不重读**文档,只做两件事: + +``` +git status -sb && git log --oneline -3 +``` + +1. 用上述命令确认落点(改到哪了、有没有未提交的东西),与上下文记忆对齐; +2. 直接从中断处继续执行,纪律沿用上下文里已载入的那套。 + +若上下文里**找不到进行中的任务**(比如 /clear 过、或换了会话误用此模式)→ 说明情况并改走模式二,不硬猜。 + +--- + +## 模式二 · 重载(`/kof c`,/clear 后的完整加载) + +### 定位任务 + +``` +grep -n "^- \[ \]" PLAN.md | head -3 +``` + +PLAN.md 按里程碑时间序排列,**第一个 `- [ ]` 就是最早的未完成任务**——接手它(命中多个只做第一个)。 + +**零命中**(当前里程碑全勾完)→ 不擅自开新里程碑,进入**立项流程**: +1. 先确认上一里程碑已收口(`git log origin/main` 全部 commit 已进 main、CHANGELOG 已记、任务已归档 PLAN-ARCHIVE); +2. 按手册 JIT 在 `PRD.md §11` 补下一里程碑的字段级规格 + 记 DECISIONS; +3. 拆任务写进 PLAN.md(**增量编辑**); +4. **等用户确认后再实现**,不许跳过确认直接写代码。 + +定位到后**先向用户报告一句**「本会话接手 M__-T__ · <任务名>」再动手——找错任务闷头干到一半,比多说一句话贵得多。 + +然后走下方【完整流程】。 + +--- + +## 模式三 · 指定任务(单个 / 批量 / 区间) + +- 单个:`/kof M3-T2` +- 批量:`/kof M3-T2 M3-T3 M3-T5`(空格分隔,按给出顺序执行) +- 区间:`/kof M3-T2..T4`(展开为 T2、T3、T4) + +批量规则: +1. 批量=用户**明确授权**在一个会话里顺序连做(等效 PLAN 里的【可批量】授权),但**逐任务独立收尾**——每个任务各自四命令绿、各自 commit,做完一个再开下一个,绝不合并提交。 +2. 队列里撞到 PLAN 标了**【单独+确认】/ 命门**的任务 → 做完它后**停下等用户确认**再继续队列(批量授权不覆盖命门确认门)。项目命门清单见 PLAN.md 头部。 +3. 某个任务失败/被阻塞 → 停下报告,**不跳过它继续后面的**(后序任务往往依赖前序)。 +4. 开工前把整个队列报告一遍:「本会话依序执行:M__-T__、M__-T__ …」。 + +然后走下方【完整流程】。 + +--- + +## 完整流程(模式二 / 三共用) + +### 第一步 · 读(不读完不许写代码) + +1. `AGENTS.md` + `CLAUDE.md` —— 协作入口、TIER1 硬规则与技术约定。 +2. `PLAN.md` —— **当前里程碑整段**:里程碑头(目标 / DoD / 原则 / 范围边界)+ 目标任务描述(即验收标准)+ 已完成任务的 Evidence 与踩坑留痕(前序设计决定都在里面)。 +3. `DECISIONS.md` —— 最新 2–3 条(当前 D 编号见索引表尾部)。 +4. 按需:涉及契约/字段 → `PRD.md §11` 对应里程碑段;涉及前端视觉 → `DESIGN.md`;工程门禁 → `ENGINEERING.md`。 +5. (v6 项目)`.vibe/project.json` 与当前 `.vibe/tasks/{task-id}.json`;与 PLAN 冲突时停下交 Integration Owner 裁决。 + +### 第二步 · 自查时效状态(用命令,不用记忆) + +``` +git status -sb # 当前分支、是否干净、与远端差距 +git log --oneline -5 # 最近提交(前序任务的落点) +gh pr list # 开放 PR +gh run list --branch main --limit 1 # main CI 状态(红着不准起跑) +{项目依赖服务的健康检查命令} # 如 docker compose ps db +``` + +- **多 Agent / 并发会话**:动手前先 claim(PLAN 任务的 状态 / Owner / Worktree / Writable Scope),确认号段已分好(里程碑号、决策号 D__);共用本地服务时错峰跑重负载测试。 +- **常设悬案**(除非任务明说,不许顺手碰):`{列出本项目当前有意保留的状态,如沙盒配置、生产数据、待办的临时开关}`。 +- **受保护文件**(改动须【单独+确认】并走 Integration Gate):契约/schema、迁移历史、锁文件、CI 配置、生成文件、设计 token。 + +### 第三步 · 执行纪律 + +1. **recon 到 file:line 再动手**。计划前提被 recon 推翻 → 改计划并在任务 Evidence 里留痕,不硬做。 +2. **契约先行**:跨层接口先在契约单一真相处定稿 → 生成/推导两端类型 → 应用层只消费,禁止两处定义。契约冻结后的破坏性变更必须新开 DECISIONS 条目。 +3. **数据迁移**:一律经工具生成、不裸写 SQL、不删改既有迁移历史;autogenerate 的产物**必须人工审**(误删系统表 / 重复索引 / 类型残留是常见坑);跑 upgrade → downgrade → upgrade 全循环再算过。 +4. **动 UI**:改界面的任务 commit 前跑**布局程序化断言**(`scrollWidth - clientWidth === 0`、最右元素不超容器右缘),在项目声明的基准视口重跑(`{移动优先 375 / 桌面优先 1280,见 DESIGN.md}`);click 后等渲染再读 DOM;四命令全绿 ≠ 布局对。 +5. **接口隔离变化**:会被替换实现的能力,签名按**未来形态**定(异步、可空),换实现时上层零改动。 +6. **文案与业务红线**:面向用户文案走 i18n key;`{列出本项目的业务红线,如:只软删除、原始数据不可覆盖、关键修改必确认+留痕、状态唯一来源}`。 +7. **批量改代码用逐条断言存在的精确替换**,不用盲正则 sed。 + +### 第四步 · 任务收尾(每任务) + +四命令绿(`{lint}` / `{typecheck}` / `{build}` / `{test}`,从仓库根跑)→ 代码改动 + PLAN.md 勾选 + **Evidence 回填**(做了什么、关键取舍为什么、实测数字、踩坑留痕、如实记录的偏差)+ DECISIONS 追加(如有),**同一个 commit** → message 用 `M{x}-T{y}: 描述` 并说清"为什么"。 + +- PLAN / PRD / DECISIONS **只增量编辑,永不重生成**;改完 `git diff` 核对 checkbox 数量与结构未被破坏。 +- 分支命名 `agent/{agent-id}/{task-id}-{slug}`;**禁止直推 main**(纯文档改动同样走分支 → PR)。 +- 禁止提交密钥、`.env`、生成物。 + +### 第五步 · 里程碑收口(仅收口任务) + +旅程走查(手册阶段 3.5:新用户走完整旅程,无断头路)→ **涉敏里程碑跑 A5 安全审计**(子代理或新会话跑,**禁止实现会话自审**;项目涉敏点见 CLAUDE.md),高危清零才准合 → 四命令绿 + `gh pr checks` 绿 → PR 合并 → CHANGELOG 记 `0.{n}.0` → 本里程碑任务整段移入 `PLAN-ARCHIVE.md`(**只移不删**)、PLAN 折叠留一行并切下一里程碑 → 删除已合并分支(本地 + 远程)→ `gh run list --branch main` 确认 main 自身 CI 绿。 + +--- + +## 逐任务循环与交接(自动驾驶) + +用户说"继续 / 下一个任务 / keep going"时,回到【定位任务】做下一个未勾任务。**你读不到自己的上下文占用**,用这个代理判据决定续跑还是交接: + +- **同会话自动续跑**:刚做完的是轻型/常规任务,且 transcript 还不大。 +- **停下等确认**:刚做完的是【单独+确认】命门任务(批量授权不覆盖命门确认门)。 +- **交接**:刚做完的是【重型】任务,或 transcript 明显很大。明确告诉用户: + > 任务 M__-T__ 已提交。上下文偏重了 —— 运行 `/clear`,再 `/kof c` 从 PLAN.md 续跑。 + + `/clear` 后 `/kof c` 可无损续跑(状态在 PLAN.md 里)。重型任务后拿不准就交接,别冒险做到一半上下文耗尽。 +- **里程碑完成**:停下汇总交付内容,提醒用户确认 CI 绿再合并。 + +全自动:用户可起 `/loop /kof c`,运行时在轮次间自动压缩上下文,不需要 `/clear`;里程碑做完停掉 loop。 + +--- + +## 项目坑位(每个项目自行填写,持续追加) + +> 这一节是本 skill 最有价值的部分:把**本项目真实踩过的坑**写成一条条可执行的规避动作,条条注明出处(任务号 / 决策号)。空着的 skill 只是模板,填满的 skill 才防事故。 + +- `{坑 1:现象 → 根因 → 规避动作(出处 M__-T__ / D__)}` +- `{坑 2:…}`