# software-engineering 技能包说明

本文件是源码包的导航与装机说明，不是技能规则本身。
规则只在 `SKILL.md` 里，改规则只改 `SKILL.md`；本文件不复述
门禁、角色细则与校验规则，复述就会漂移。

版本与状态以 `SKILL.md` 文首为准：v0.2，2026-10-30，草稿；
其文首自述未提 PR、未部署生产、未改任何生产代码。
本文件只补说明，不改规则、不合并、不部署。

## 用途

面向“从零做一款软件、尤其是要同时做 web、macOS、Windows、
iOS、Android 多个客户端”的任务：按产品规划、产品设计、架构契约、
多客户端并行开发、联调测试、验收的顺序，用协调员任务派生角色线程
推进，契约冻结后各客户端只在自己目录内开发，最后走评审合并与用户验收。

用与不用的判定只在 `SKILL.md` 的“何时用 / 何时不用”两节，
本文件不另立标准。只做单文件小改动、只问概念时不用本技能，
这是 `SKILL.md` 的原话指向，不是本文件的补充规则。

## 包内文件一览

源码位置是 `cloud/skills/software-engineering/`，包内文件如下：

- `SKILL.md`：唯一规则权威，含正文与文末附录随附版。
- `README.md`：本文件，导航与装机说明，不进入租户。
- `CHANGELOG.md`：变更时间线，见下文“与 CHANGELOG 的分工”。
- `templates/roles/`：附录的 9 个编辑源，见下文“附录溯源”。
- `tools/check_appendix.py`：附录校验脚本，只校验，不改 `SKILL.md`。

## SKILL.md 章节结构（只列名，不复述规则）

正文节：

- 何时用 / 何时不用
- 核心原则（协调员和所有角色线程都必须遵守）
- 阶段 DAG（不是所有线程同时开，是按门禁、分阶段开）
- 门禁表
- 接单选型：协调员第一件事是问，不是写代码
- 角色线程矩阵
- 协调员派生子任务的必填字段
- 待办机制（不依赖提示词注入）
- 契约冻结与变更协议
- 目录与分支规则
- GitHub 保证（每线程一分支、一 PR、一合并门），下含分支、
  PR 交付、合并门、合并方式与合并记录、发布与回滚、
  安全六个小节
- 测试与验收
- 失败、续跑与成本
- 诚实边界：原生客户端
- 校验（协调员每过一个门禁自查一次）

附录节：

- 附录：角色模板（播种随附版），下含 9 章附录角色，
  每章标题注明其来源文件，见下文“附录溯源”。

## 附录溯源

附录 9 章的编辑源在 `templates/roles/` 下，文件与章一一对应：

`00-coordinator.md`、`01-product-manager.md`、`02-architect.md`、
`03-designer.md`、`04-client-developer.md`、`05-backend.md`、
`06-qa.md`、`07-acceptance.md`、`08-shared-core.md`。

校验入口（仓库根目录执行）：

```sh
python3 cloud/skills/software-engineering/tools/check_appendix.py
```

该脚本默认校验模式逐章比对源与附录；`--emit` 模式只把拼接后
的附录规范形式打印到标准输出，供编辑者起草参考，绝不是可直接
覆盖 `SKILL.md` 的字节补丁。校验的规范形式、允许差异与失败条件
以脚本注释为准，本文件不另抄一份；补齐的时间线见 `CHANGELOG.md`。
任一侧改动都应先被校验拦住，而不是悄悄漂移：改附录先改源，
再按技能轨重发附录，脚本本身不替编辑者改 `SKILL.md`。

## 播种行为

装机路径（`SKILL.md` 文首原话指向）：

- 源码位置：`cloud/skills/software-engineering/SKILL.md`
- 播种后租户内位置：`<codex-home>/skills/software-engineering/SKILL.md`

播种实现是 `cloud/skill_seed.py`，本段只是其摘要，冲突以实现
与测试为准：

- 只复制各技能的 `SKILL.md` 一个文件；`README.md`、`CHANGELOG.md`、
  `templates/`、`tools/` 均不进入租户目录。
- 目标缺失则复制；目标与源码相同则不动；目标已被租户改动
  （内容不同）则绝不覆盖，记入 `skills_skipped_differ` 并原样保留。
- 包内某技能目录缺 `SKILL.md` 时跳过，不凭空捏造。
- 因此租户任务内只能看到 `SKILL.md` 随附的附录全文，附录仍是
  租户侧的权威版本；本文件与附录源只在源码包一侧可见。

删除行为按现行实现写，不按设想写：租户已删 `SKILL.md` 会在
下次播种时重建（missing 即复制）。删除保留机制见 tombstone 设计，
行为以 skill_seed 实现为准。

## 与 CHANGELOG 的分工

同一说明只落一处，本文件与 `CHANGELOG.md` 不复制粘贴同一份说明：

- `README.md`（本文件）：包是干什么的、文件都在哪、从哪验证、
  播种后租户能看到什么。回答“怎么找到、怎么核对”。
- `CHANGELOG.md`：何时补了什么、此前缺什么、缺的那段历史是否
  可追溯。回答“这包经历了什么变化”。此前 v0.1 → v0.2 的 5 个
  P0 缺口明细因当时无此文件而无法从本文件追溯，`CHANGELOG.md`
  开篇已明说不编造那段历史；2026-10-31 起的附录溯源补齐条目
  记在那里，不重复抄到本文件。
- `SKILL.md`：规则本身，唯一权威。
- `tools/check_appendix.py` 的注释：校验的规范形式权威。
- `cloud/skill_seed.py` 及其测试：播种行为权威。

改规则改 `SKILL.md`，改溯源记录改 `CHANGELOG.md`，改校验规则
改脚本注释与对应测试；本文件只在导航、路径或分工本身变化时才改。

## 已知边界

- 本轨只补说明：不改 `SKILL.md` 正文语义，不改任何规则，
  不改播种行为，不合并，不部署。
- 租户已删 `SKILL.md` 会重播种，见上文“播种行为”；删除保留
  未落地为实现，不以本文件声称已实现。
- 附录分隔符不统一的现状与校验处理见 `CHANGELOG.md` 与脚本注释，
  本文件不另行规定、不强行统一 `SKILL.md`。
- `SKILL.md` 正文还提到 `templates/artifacts/` 下的模板名
  （PRD 大纲、接单问卷、验收清单）；本包 `templates/` 目前只有
  `roles/`，artifacts 模板不在本轨补齐范围，本文件不声称它们已存在，
  引用状态以 `SKILL.md` 原文为准。
- 播种落盘与 `skills/list` 发现已验证；任务内模型实际调用技能
  尚未验证，本文件不声称已验证（见 `cloud/skill_seed.py` 的
  honest boundary 注记）。