163 lines
16 KiB
Markdown
163 lines
16 KiB
Markdown
---
|
||
name: divine-lot-dev
|
||
description: 神之一手（divine-lot-dev）—— 最强的 AI Native 项目开发逻辑：面向文档的开发模式，由人与 AI Code Agent 的反复讨论驱动。通过 docs 下「终极目标 / 计划 / 设计约束 / 迭代记录 / 需求池」五个强约束目录管理项目；支持项目初始化（自动建立目录结构）。当用户要求在本项目内开发、讨论、规划或复盘时使用本技能。
|
||
whenToUse: 在 one_divine_lot 仓库中从事任何开发、规划、讨论、审查或复盘工作前，先阅读本技能对齐神之一手框架；项目约定与本技能冲突时以本技能为准。
|
||
---
|
||
|
||
# 神之一手（divine-lot-dev）
|
||
|
||
**神之一手** = 最强的 AI Native 项目开发逻辑。
|
||
|
||
核心思想：**项目由文档驱动，文档由讨论产生**。人与 AI Code Agent 通过反复讨论推进项目，每一次讨论的结论都以强约束文档的形式沉淀在 `docs/` 下，文档反过来约束后续的每一次开发动作。
|
||
|
||
## 1. 工作模式：面向文档的讨论式开发
|
||
|
||
```
|
||
讨论（人 ↔ AI） → 结论沉淀为文档 → 文档强约束下一步动作 → 执行 → 记录 → 复盘 → 新一轮讨论
|
||
```
|
||
|
||
- **讨论是发动机**：需求、方案、取舍都先讨论清楚，再落文档、再动代码。
|
||
- **文档是刹车和方向盘**：一切开发动作必须可回溯到某个文档条目；文档未覆盖的改动不允许发生。
|
||
- **Agent 的角色**：不只是写代码，而是参与讨论、维护文档、按文档执行、诚实记录结果。
|
||
|
||
## 2. docs/ 五大强约束目录
|
||
|
||
`docs/` 下五个目录各自承担唯一职责，**职责不可混淆、不可绕过**。目录名带序号，**序号即流程顺序**：从 01 到 05 完整走完一轮项目推进，阅读与执行都按序号从头到尾进行。每个目录内有 `说明.md` 定义其角色与强约束（细节随讨论演进）。
|
||
|
||
| 目录 | 角色（一句话） | 强约束（初始定义） |
|
||
|---|---|---|
|
||
| `01-终极目标/` | 项目存在的唯一理由 | 内容唯一；变更必须经重大讨论并记录理由；是其他一切目录的最终裁决依据 |
|
||
| `02-计划/` | 目标分解后的执行方案，支持不同粒度 | 必须从终极目标派生；计划条目必须有明确范围与验收；计划未覆盖的事不做 |
|
||
| `03-设计约束/` | 设计与技术的强制规范，下分三个文档模块（产品功能 / 技术方案 / UI交互） | 后续迭代必须以本目录为依据；规范变更需讨论并记录理由；不得与终极目标冲突 |
|
||
| `04-迭代记录/` | 执行过程的事实档案，每次迭代一个子目录（迭代目标 / 技术实现方案 / 验收标准） | 只记录事实（做了什么、结果如何），不写感想；追加式，不改写历史 |
|
||
| `05-需求池/` | 所有待办需求的入口 | 统一格式登记；每条需求维护状态（起草/讨论中/已定稿）与更新日期；讨论中的想法先入池；**只有已定稿的需求才可进入计划/迭代范围，未定稿的需求停留在池中** |
|
||
|
||
> **设计约束的文档模块**：`03-设计约束/` 下三个文档模块，各自以**列表**记录约束条目，每条含「编号 / 约束说明 / 添加日期 / 生效状态 / 失效日期 / 最后一次变更描述」：
|
||
> - `产品功能约束.md`：产品功能层面的约束（功能边界、行为定义、不可违背的产品规则）
|
||
> - `技术方案约束.md`：技术方案层面的约束（技术栈、架构、实现规范、依赖原则）
|
||
> - `UI交互约束.md`：UI 与交互层面的约束（视觉风格、组件、交互行为）
|
||
> - 后续讨论确定的设计/技术/产品约束与变更，直接更新对应模块列表：新增条目追加、变更条目更新说明与日期、失效条目标记状态与失效日期。引用时用编号（如 `产品约束-001`）。
|
||
> - **最后一次变更描述**：概括该约束最近一次变更（新增 / 变更 / 失效）讨论的最后一层结论，写入该列以便追溯；新增时写"新增"讨论的结论，变更/失效时更新为当次讨论的结论。
|
||
|
||
> **迭代记录的组织结构**：`04-迭代记录/` 下每次迭代一个子目录。目录已位于迭代记录下，目录名不再重复"迭代"前缀，直接为 **`<编号>-<目标名称>`**（如 `01-建立神之一手框架`），编号放最前、后面直接跟本次迭代的目标名称，子目录内含三份文档：
|
||
> - `迭代目标.md`：本次迭代的目标、目标描述、目标的讨论过程，以及对项目主理人（老师）的配合需求
|
||
> - `技术实现方案.md`：实现该目标对应的技术实现方案
|
||
> - `验收标准.md`：本次迭代的验收标准线（验收标准在哪里）、验收方法、验收目标 —— 明确如何判定本次迭代是否达成
|
||
> - **与需求池联动**：迭代目标若引用需求池中的需求，需求池索引记录需补充「实现该需求的迭代」与「需求实现状态」两要素，双向可追溯。
|
||
|
||
> **需求状态管理**：`05-需求池/` 的每条需求在索引中维护两个状态字段：
|
||
> - **状态**：`起草`（刚入池，想法未成形）→ `讨论中`（正在讨论、未确定）→ `已定稿`（讨论确定、可进入计划/迭代）。状态按此单向推进，回退需讨论说明。
|
||
> - **更新日期**：最近一次状态变更或内容更新的日期，随每次变更刷新。
|
||
> - **与入范围门槛的对应**：只有状态为「已定稿」的需求才可进入计划范围或迭代工作范围；起草 / 讨论中的需求停留在需求池。
|
||
|
||
> **需求状态流转责任**（2026-08-28 定）：状态流转由 **AI 提议 + 老师确认** 驱动 —— AI 负责整理需求、提出状态变更建议（起草→讨论中→已定稿），老师拍板确认后 AI 更新状态；回退同样需老师确认并记录理由。
|
||
|
||
> **需求定稿标准（三要素）**（2026-08-28 定）：需求进入「已定稿」需同时满足 —— ① **边界清楚**（做什么 / 不做什么明确收敛）；② **核心逻辑明确**（关键决策点：数据模型 / 交互 / 技术方案都有讨论结论）；③ **老师确认**（老师明确表示需求可定稿）。三条全满足才可进入计划 / 迭代范围；R-002 为完整实践样本。
|
||
|
||
> **需求池目录结构**：`05-需求池/` 内部按以下结构组织需求：
|
||
> ```
|
||
> 05-需求池/
|
||
> ├── 说明.md # 目录说明与约定
|
||
> ├── 需求池索引.md # 当前工作需求总览（状态流转记录）
|
||
> ├── 草稿/ # 需求收集：临时想法、未成形需求（状态=起草），成熟后转正到根目录
|
||
> ├── 已完成/ # 已完成需求的归档（每个需求一个文件，含需求摘要+讨论记录）
|
||
> └── 丢弃/ # 被拒绝/搁置需求的归档（记录需求+丢弃原因）
|
||
> ```
|
||
> - **根目录 = 当前需求工作目录**：正在讨论、已定稿、待实现的需求以文件形式放在根目录。
|
||
> - **草稿/ → 根目录**：需求从草稿"转正"为正式需求（状态进入讨论中/已定稿）时移入根目录。
|
||
> - **已完成/ 与 丢弃/**：需求实现后移入已完成；拒绝/搁置移入丢弃（记录原因）。两者均为归档，追加不改写。
|
||
> - **登记格式**：每条需求索引记录含「编号 / 标题 / 描述 / 来源 / 优先级 / 状态（起草/讨论中/已定稿）/ 更新日期 / 实现迭代 / 实现状态」。
|
||
|
||
> **需求归档检查清单**（2026-09-01 定，源自 R-005/R-008 归档实践）：
|
||
> 需求实现完成后归档，按序执行 —— ① **核实完成**：对应迭代复盘存在且标记「验收通过」，索引中实现状态为「已实现」；② **补归档头**：归档文件加「归档日期 / 需求状态：已完成 / 实现迭代 / 讨论记录索引」头部；③ **移入归档**：需求文件从根目录移入 `已完成/`；④ **更新索引**：主索引保留条目，实现状态改为「已实现（已归档）」，描述标注归档路径；⑤ **双向追溯**：迭代记录与需求池互相引用（迭代复盘关联需求编号，需求归档引用迭代复盘路径）。归档只追加不改写历史。
|
||
|
||
> **草稿转正清理**（2026-09-01 定，源自 T-008 转正残留教训）：草稿转正为正式需求（T→R）时，**必须清理草稿残留的头部/模板内容**（如「状态：起草」「登记日期」旧头部），确保正式文件只有一套头部；转正后删除草稿文件，索引同步更新（草稿行状态 → 已转需求 R-xxx）。
|
||
|
||
> **关于粒度**：计划不是单一粒度。一个计划可以是"概念范围大一些的阶段航点"，也可以是"可直接执行的小任务"。两者本质相同 —— 都是对目标的分解 —— 只是范围大小不同，统一归入 `02-计划/`，通过粒度标记区分。
|
||
|
||
### 文档之间的流转关系
|
||
|
||
```
|
||
05-需求池 ──(讨论→确定→排优先级)──▶ 02-计划 ──(执行)──▶ 04-迭代记录
|
||
▲ │
|
||
└────────(复盘，对照计划)─────────────────────┘
|
||
│
|
||
▼
|
||
03-设计约束 ◀──(迭代须依据)── 02-计划
|
||
│
|
||
▼
|
||
01-终极目标 ──(验证)──▶ 持续迭代
|
||
```
|
||
|
||
> **入范围门槛**：`05-需求池 → 02-计划` 之间有一道门槛 —— **只有状态为「已定稿」的需求才允许跨过**。起草 / 讨论中的需求停留在需求池，不得进入计划范围，也不得进入迭代工作范围。
|
||
|
||
> 注：序号反映**阅读与裁决的层级顺序**（01 最高），实际推进节奏按 `05 → 02 → 04 → 01` 的流转闭环走，且每次进入计划/执行都必须先对照 `03-设计约束`，两者不冲突。
|
||
|
||
## 3. 功能：项目初始化
|
||
|
||
**触发时机**：在新项目 / 空项目初始化时，建立当前项目的目录结构。
|
||
|
||
**初始化动作**：
|
||
|
||
1. 建立 `docs/` 五大强约束目录：`01-终极目标/`、`02-计划/`、`03-设计约束/`、`04-迭代记录/`、`05-需求池/`。
|
||
2. 每个目录写入 `说明.md` 骨架：角色 / 强约束（初始定义）/ 待讨论细节，内容与本节框架一致。
|
||
3. `03-设计约束/` 下建立三个文档模块：`产品功能约束.md`、`技术方案约束.md`、`UI交互约束.md`，各含六列列表骨架（编号 / 约束说明 / 添加日期 / 生效状态 / 失效日期 / 最后一次变更描述）。
|
||
4. `05-需求池/` 下建立需求池结构：`需求池索引.md`（需求索引骨架，每条含「编号 / 标题 / 描述 / 来源 / 优先级 / 状态（起草 / 讨论中 / 已定稿）/ 更新日期 / 实现迭代 / 实现状态」字段）+ `草稿/`、`已完成/`、`丢弃/` 三个子目录。
|
||
5. 检查 `.agents/skills/divine-lot-dev/` 是否存在（skill 本身），不存在则提示先安装 skill。
|
||
|
||
**初始化原则**：
|
||
|
||
- **不覆盖**：已存在的目录或文件不重复创建、不覆盖已有内容。
|
||
- **可校验**：初始化完成后输出目录结构清单，供确认。
|
||
|
||
## 4. 开发流程（框架层）
|
||
|
||
1. **新想法 → 需求池**：任何新需求、新想法先登记入池，不直接进代码。
|
||
2. **需求 → 讨论 → 定稿**：对池内需求进行讨论，需求状态随讨论推进（起草 → 讨论中 → 已定稿）。**未定稿（起草 / 讨论中）的需求停留在需求池**，不进入计划与迭代。
|
||
3. **已定稿的需求 → 计划**：只有状态为「已定稿」的需求，才从终极目标派生计划（含大粒度阶段航点与小粒度任务，按需拆分）。
|
||
4. **计划 → 对照设计约束 → 执行**：进入计划与执行前，先对照 `03-设计约束/` 中的设计/技术/产品设计规范，确保实现有规范依据。
|
||
5. **计划 → 执行 → 迭代记录**：按计划执行，每次迭代的事实写入迭代记录。
|
||
6. **迭代 → 复盘 → 计划/需求池**：对照计划检查进度，更新计划状态与需求池流转。
|
||
7. **计划 → 终极目标**：阶段性验证，确认终极目标的推进与修正。
|
||
|
||
## 5. 质量门禁（框架层）
|
||
|
||
- **文档先行**：代码改动必须有对应文档条目（计划/需求池）支撑。
|
||
- **入范围门槛**：只有状态为「已定稿」的需求才可进入计划范围或迭代工作范围；起草 / 讨论中的需求不得进入，只停留在需求池。
|
||
- **规范约束**：实现必须符合 `03-设计约束/` 的规范；无规范依据的实现需要先补规范或讨论豁免。
|
||
- **记录诚实**：迭代记录只写事实，成功失败都记录，失败是复盘的原料。
|
||
- **约束优先**：文档强约束 > 临时便利；违反约束的改动需要讨论并修订文档。
|
||
- **语义迁移核对**（2026-09-01 定，源自迭代 06 addToStrategy Bug）：改造/迁移方法时，若方法语义发生变化（如「新增量」变「绝对目标量」、存储整体读写变单条生命周期），必须 —— ① 显式命名语义（如 `_applySharesForStrategy(target)` 注释标明参数为绝对目标）；② 逐调用点核对参数含义；③ 用真实 API 走一遍完整 CRUD 回归（不能只靠隔离单测，隔离测试可能掩盖语义混淆）。
|
||
|
||
## 6. skill 自我维护约定
|
||
|
||
本 skill 在项目使用过程中持续演进，遵循以下维护约定：
|
||
|
||
1. **发现问题即补充**：在项目实践中，若发现某个管理约束缺失、定义不清晰，或项目文件缺失（如缺少某个说明.md、索引文件、字段），**主动将缺失的约束或文件定义补充进本 skill**，而不是绕过或临时应付。
|
||
2. **约束沉淀优先**：实践中的经验教训（哪些流程走不通、哪些约定被违反）应沉淀为 skill 的强约束或说明，避免同类问题重演。
|
||
3. **补充需记录**：每次补充 skill 内容时，说明补充的原因（源于哪次实践 / 哪个问题），便于追溯。
|
||
4. **保持自洽**：新增内容不得与既有约束冲突；冲突时先讨论再修订。
|
||
5. **先改 skill 再落工作**：确定的管理约束先写入 skill 定义，再同步到具体项目的 docs 工作内容。
|
||
|
||
## 7. 与 DSH 的协作约定
|
||
|
||
- 若功能以 DSH 插件形式提供，遵循 DSH 的 Cordis 插件规范：`apply(ctx)` 内使用 `ctx.effect()`/`ctx.on()` 管理副作用，`ctx.get(name)` 读取可选服务，插件命名用 `name`/`inject`/`apply` 形式导出。
|
||
- 复用 DSH 内置能力（文件、shell、MCP、subagent 等）优先于自行实现。
|
||
- 修改 DSH 宿主组成（host composition）或 agent preset 前，先加载 `editing-cordis-compositions` 技能。
|
||
|
||
## 8. 待讨论的细节（随讨论逐步填充）
|
||
|
||
> 以下为框架已定、细节待讨论的开放问题清单，每轮讨论聚焦其中一项，结论回写本技能与对应 `说明.md`。
|
||
|
||
- [ ] 终极目标：文档格式、变更流程、与计划的校验关系
|
||
- [ ] 计划：粒度的区分方式（如何标记阶段航点 vs 小任务）、完成标准写法、依赖表示方式、与迭代的对应关系
|
||
- [x] 设计约束：文档模块与记录格式（三个模块：产品功能 / 技术方案 / UI交互；列表条目含编号、约束说明、添加日期、生效状态、失效日期）
|
||
- [ ] 设计约束：变更流程、与计划的校验关系
|
||
- [x] 迭代记录：组织结构（每次迭代一个子目录，含迭代目标 / 技术实现方案 / 验收标准；与需求池索引联动）
|
||
- [ ] 迭代记录：验收标准的写法（标准线如何划定、验收方法、验收目标）
|
||
- [ ] 迭代记录：记录粒度、编号规则、复盘模板
|
||
- [x] 需求池：登记格式（含状态字段：起草/讨论中/已定稿 + 更新日期，以及"实现迭代 / 实现状态"联动字段）、状态流转的具体定义（AI 提议 + 老师确认，2026-08-28 定）
|
||
- [ ] 需求池：优先级规则（P0-P2？MoSCoW？如何定级）
|
||
- [x] 入范围门槛：只有确定的需求才可进入计划/迭代范围，未确定的需求停留在需求池
|
||
- [ ] 讨论本身的规范：讨论如何发起、如何收敛（需求定稿判定标准「三要素」已定：边界清楚 + 核心逻辑明确 + 老师确认，2026-08-28）
|