Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions README.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`:持久化项目状态与调度拓扑。
Expand Down
143 changes: 143 additions & 0 deletions skills/kof/SKILL.md
Original file line number Diff line number Diff line change
@@ -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:…}`