On-MyWay —— 老实按我的要求来！

> 实现手段：引导词（定框架）+ 模板（锁格式）+ JSON Schema（锁结构）+ 脚本（校验/渲染/审计/索引）四件套——引导词是天然的软约束，用 JSON+脚本等硬性手段让 AI 老实沿着既定的轨道运行。
>
> 配套目录：templates/（文档模板）、schemas/（JSON Schema + 文档结构契约 + 路由契约）、scripts/（校验/渲染/审计/索引）。
>
> 详细行为规则见正文 0.2/2/3/4/5 各章。

0.0 与 Plan-And-Execution 类 skill 的区别

Plan-And-Execution 类 skill 走完流程照样跑偏。根因三：

• 引导词是软约束，AI 想听就听；
• 过于简单或过于形式主义，不是人干活儿的真实场景；
• 缺执行路径和硬约束，只约束流程不约束质量。

本技能的核心：约束产出质量（不是流程表演）、文档是给人读的、AI 的信息 AI 自己消化。

0.1 适用边界

主要适配以下场景：

• 执行复杂多步任务：功能多模块、开发跨多次会话；
• 开发复杂项目：项目真正用于生产——文档能交接、代码能维护、逻辑经得起验证；
• 用户显式触发：说「用 on-myway 方法论」即介入（见 0.2），无论场景。

其余场景（纯问答、临时笔记、探索性讨论）不强制，除非用户显式触发。

不属于文档的内容，禁止写进文档：对话流水、调试过程、git diff、代码细节——这些属于 git log / 代码注释 / 对话记录。

0.2 触发与退出（介入开关）

方法论默认不介入；用户说「用 on-myway 方法论」后介入，本项目所有任务自动走本方法论，直到明确说「退出 on-myway 方法论」。

• 未介入时：不强制走完整方法论；但显式触发词（「保存到文档 / 保存信息到文档 / 记一下 / 存档」）仍作为单次介入点生效。
• state.md 格式固定：状态：介入中 或 状态：未介入（audit F8 硬校验，写坏即打回）。

1. 主循环

以「需求文档待办列表」为中枢的循环：

① 问（问清楚） → ② 答（你回答 + 确认）
        ↓
③ 记 → 需求文档（把要做的事分好类，形成待办列表）★中枢
        ↓
④ 干（按需求文档待办列表逐条推进开发；多任务先拆分、各自独立走流程）
        ↓
⑤ 记进度 + 答汇报（做完记录进度与完成情况，同时汇报进展）
        ↓
   遇问题 → 回到 ① 问（穿插 问/答/记 小循环）

开工前置（AI 唤醒协议）：每次会话开始 / 切换 Agent / 会话压缩后 / 断点续传，先读 .onmyway/index.md 检索地图（含介入状态）定位，再按需加载对应章节——禁止全量扫描 5 份文档；介入中则全程走本方法论，未介入不强制（介入开关见 0.2，索引机制见 5.6）。

2. 问（交互行为：先问清楚）

2.1 触发条件

• 需要时才问：只有遇到「无法自主决策」的点才问；能自己定、无歧义的，直接干。
• 必要性自审：不必要就不问。AI 必须先想清楚「这问题必须问人么？」。

2.2 六条总则

1. 必要性自审：不必要、能自己定、无歧义，就不问
2. 备全单问：所有待问问题先列成清单排队，一轮只问一个；禁止同时抛多个问题，也禁止想到哪问到哪
3. 先做功再问：AI 自己先想清目的/方案/影响，才来问
4. 必带「为什么」：说明背景与必要性，让人知道这问题值不值得答
5. 信息闭环：拿到的东西怎么用、用完怎么处理，说清楚
6. 带全局定位：从宏观到微观，先交代「现在在哪、为什么在这」，再抛细节（大型项目后期尤其重要，防止用户不知所云）

2.3 三个结构

① 决策问（选哪个）

目的 → 背景（为什么不能自主决策）→ 方案（可量化：成本/工期/风险）→ 建议（倾向哪个+理由）

② 信息问（缺什么）

需要什么信息 → 为什么需要（卡在哪、没有会怎样、说明必要性）→ 拿到后怎么用 → 用完后怎么处理

③ 确认问（干不干）

我准备做什么 → 为什么（原因、背景、必要性）→ 影响（风险 → 是否可逆 → 影响范围）→ 请确认

2.4 硬约束（问前三闸 + A/B 分层）

问之前过三道闸，任一不过即不问：

• Q1 必须问么？ 能自决、无歧义 → 转自决，不问
• Q2 做功了么？ 无方案、无倾向、无可量化选项 → 回去做功
• Q3 备全了么？ 未把全部待问问题列成队列 → 先列队列，再取队首

输出按问的类型分层施加：

一轮一问（结构强制，非引导）：A 路线 JSON 顶层只有 queue（全部待问问题清单，按优先级排序，队首为当前所问）+ current（单问内容）两个字段。current 是单对象不是数组——结构上不存在「一轮多问」的合法形态。人答后出队，下一条重新生成。

机制链：列全队列 → 取队首生成 JSON → 校验（不符打回）→ 渲染呈现 → 人答后出队 → 下一条。

Schema 契约：

• 决策问 → schemas/question-decision.schema.json：目的 / 背景（为什么不能自主决策）/ 方案 ≥2 且可量化（成本·工期·风险）/ 建议（倾向 + 理由）
• 确认问 → schemas/question-confirm.schema.json：行动（做什么）/ 理由（为什么）/ 影响（风险·是否可逆·影响范围）

3. 答（交互行为：怎么交代结果）

「答」= AI 向用户交代结果的全部输出规范，四场景：

输出按场景分层施加（与「问」的 2.4 对称）：

3.1 答复场景（四步，B 路线：模板约束）

① 复述确认（防跑偏）—— 用自己的话概括「我理解你是 X」，有歧义只针对歧义点澄清
② 决策落定（防模糊）—— 一句话定论：选了什么 / 给了什么 / 授权了什么
③ 转化行动（防原地打转）—— 我接下来做 1. 2. 3.
④ 分类沉淀（防失忆+防丢失）—— 给人看的→人读文档；给 AI 看的→AI 记忆层；答过的问题→不重问

套用 templates/答-答复.md 填空，禁止自由发挥、禁止增删章节。第①步填不出来说明没听懂，第③步填不出来说明没想清楚——先回去做功，再回来答复。

3.2 交付 / 总结 / 异常场景：JSON 硬约束（C1）

交付（改动文件总结）、总结（任务收口）、异常（卡住/报错）三个场景，必须输出符合 JSON Schema 的 JSON，经 scripts/validate.py 校验、scripts/render.py 渲染成表格呈现。Schema 定义见 schemas/。

• 交付场景 → schemas/deliver.schema.json
• 总结场景 → schemas/summary.schema.json
• 异常场景 → schemas/exception.schema.json

机制链：生成 JSON → 校验（不符打回重来）→ 渲染成表格。

Schema 契约：

• 交付 → 文件定位 / 作用 / 改动 / 与之前区别 / 影响，六要素逐文件全必填
• 总结 → 目标 / 收口待办（todo_refs 锚定需求文档，限单条——一个任务一份总结，多任务分别收口分别汇报） / 完成情况 / 关键改动 / 逐层验证（层级+方法+结果） / 遗留 / 沉淀去向（essence+target 结构化，逐条过 route 校验，干完必记对地方）；todo_refs·done·key_changes·verification 强制非空（防空交付收口、防一句话假验证，与 dev-order 交叉对账见 4.4）
• 异常 → 定位 / 现象 / 根因 / 影响 / 已尝试 ≥1 / 下一步 ≥1；三处强制非空（防不诊断就上报、防零尝试甩锅、防不带方案踢回问题）

> 另有干环节的开工声明 → schemas/dev-order.schema.json（机制见 4.4），与总结场景对账联动。

4. 干（开发行为：再动手）

按需求文档待办列表逐条推进，只管高层 + 中层 + 开发顺序：

4.0 多任务拆分（一次多个需求时，先拆再干）

用户一次提出多个需求/任务时，先分类拆分，禁止混在一起干：

1. 拆：分类拆成独立待办（各自 REQ-xxx，进需求文档拆解表）；拆分时标出共享依赖与冲突（两个任务动同一文件/同一数据 = 冲突，需排期先后）
2. 独立走流程：每个任务各自走完整干流程——各自开工三查（4.1）→ 各自 dev-order 声明（4.4）→ 各自实施 → 各自验证 → 各自收口汇报（一份总结只收口一个任务，todo_refs 限单条）
3. 分别汇报：禁止打包混装、禁止笼统交付——用户要的是「每件事各自办得怎么样」，不是「都搞定了」

> 硬约束天然配合：dev-order 本来就每待办一份（结构上不存在多任务混一份声明的合法形态）；summary 的 todo_refs 限单条（结构上不存在一份总结混装多任务收口的合法形态）。

4.1 高层（防失控）

• 先对齐：动手前读记忆（AI 记忆层）+ 需求文档待办列表，明确本条要干什么、边界在哪
• 开工三查（动手前，结果落进 dev-order 的 precheck，见 4.4）：
• 查上游：本任务依赖谁（接口/数据/模块/他人产出）？就绪么？不就绪怎么办？
• 查下游：本任务影响谁（消费方/调用方/报表/看板）？影响是什么、方案是什么？数据类改动重点——字段/结构/口径变化必须逐个列全下游消费方，写明旧数据兼容与迁移方案
• 查条件：开工条件齐了么（环境/账号/权限/数据备份/需求确认）？任一不齐 → 不开工，先解决或走「问」环节
• 危险确认：破坏性 / 不可逆 / 生产环境操作 → 先走「确认问」
• 不跑偏：按已确认的方案执行，不擅自扩大范围
• 小步可验证：每步能验证成功，不留「不知道对不对」的状态

4.2 中层（干活标准，内置一套，项目可覆盖）

• 代码规范：遵循项目已有配置（如 ruff / ESLint / Prettier）
• 测试：关键路径要有测试覆盖
• commit 规范：约定式提交（feat: / fix: / docs: 等）

> 项目若有自己的规范，以项目为准，覆盖本内置默认值。

4.3 开发顺序（防空壳 / 防假装完成 / 防不符合预期）

动手实现每个功能前，先按「数据 → 后端 → 前端 → 联调测试」自底向上分层设计与落地。每一层先判断「是否涉及」，不涉及则跳过，不硬造：

1. 数据：是否涉及数据交互？需要数据库吗？需要则——
   - 设计数据模型，造好测试数据
   - 明确数据如何读写存取、数据链路如何设计
   - 明确调度方式：独立调度服务，还是业务代码管理即可
   - 判断读写服务：独立编写，还是复用已有公共读写模块（无则考虑是否新建）
2. 后端：功能如何实现？业务逻辑如何串联？需要则——
   - 拆解业务逻辑：入口在哪、主干流程怎么串联、异常与边界分支有哪些
   - 复用判断：已有服务 / 工具函数可复用则复用，无则新建（先判断是否值得抽公共模块）
   - 设计 API：路由、参数、返回结构、错误码，与前端约定好再动手
   - 跨模块交互：与前端 / 其他模块的接口边界先定清楚（先判断是否涉及）
3. 前端：页面如何设计与布局？需要则——
   - 页面结构：路由、组件划分、状态管理放哪
   - 接口对接：调用哪些后端 API、数据结构如何映射到页面
   - 数据展现：列表 / 图表 / 表单如何呈现，空态 / 加载 / 错误三态如何处理
   - 交互设计：按钮 / 弹窗 / 提示等操作，以及操作后的反馈
4. 测试：先测数据 → 再测后端功能 → 最后测前端展现。
   - 数据层：读写链路正确 + 数据内容正确（字段完整、数值准确、格式合规）
   - 后端层：API 行为正确，含边界与异常分支
   - 前端层：渲染与交互正确
   - 验证方式与结果逐层记入总结场景的 verification 字段（层级+方法+结果，与 dev-order 对账，见 4.4）

> 原则：先数据、再后端、再前端、最后联调测试。每一层都要真实落地并验证，禁止交付空壳、禁止假装完成。

4.4 硬约束（dev-order 开工声明 + cross 交叉对账）

「写代码 / 改代码」类待办（REQ-xxx），动手前必须生成开发顺序声明（开工三查 + 逐层自检）并通过校验；纯文档/配置类待办豁免。不声明依赖、层级和理由，就没有合法的开工形态。一个待办一份声明（多任务各自声明，见 4.0）。

机制链：生成 dev-order JSON → scripts/validate.py 校验 → scripts/render.py 渲染呈现 → 按声明逐层落地 → 收口时与总结场景交叉对账。

• Schema → schemas/dev-order.schema.json：
• todo_ref（待办编号）+ todo_desc + precheck 开工三查：
  • upstream[]：依赖的上游 + 是否就绪；未就绪 → plan 必填（应对路径），未就绪不许开工
  • downstream[]：受影响的下游 + 影响 + 应对方案，列出即三条全必填——数据类改动的重点闸（字段/结构/口径变化必须写明旧数据兼容与迁移）
  • ready[]：开工条件 + 是否就绪；不就绪 → plan 必填，不齐不许开工
• layers[] 四层全列（data / backend / frontend / test），每层 involved——涉及 → deliverables 必填（产出文件，防空壳，可拿 git diff 对照）；不涉及 → skip_reason 必填（防偷偷跳层，尤其测试层）
• 声明文件存 .onmyway/dev-orders/<REQ-xxx>.json（过程工件，不占 5 文档槽位，随 git 走）
• 交叉对账：scripts/validate.py cross <summary.json> <dev-orders目录>——summary 以 todo_refs 锚定待办（限单条，一份总结只收口一个任务），逐 dev-order 核对层级齐全且顺序合法、involved=true 的每一层在 summary.verification 有对应验证记录；缺记录即打回，不许收口
• 收口回写：cross 对账 + 文档审计（5.5 audit）全部通过后，把各待办状态回写需求文档章节②（✅ / 🔄 / ⬜）

> 边界（诚实声明）：deliverables 列出产出文件路径，脚本验不了内容真假——「禁假装完成」靠声明+对账把概率压低，非物理杜绝，最终以 git diff / 运行结果为准。

5. 记（文档行为：最后记录）

铁律：人类不读 AI 的过程信息。 过程性内容（上下文、思考、调试、决策过程）只进 AI 记忆层或留在对话/git 里；人读层只收结论，按人类方式组织、模板锁定、限量封顶。人读层被污染 = 人类放弃审阅 = AI 胡来的自由——这是本技能要堵死的第一个溃口。

5.0 记的入口（两触发 + 自动路由）

写文档不靠用户点名，靠两类时机自动触发：

① 显式触发（用户说「保存到文档 / 保存信息到文档 / 记一下 / 存档 / 记住这个」）：
识别触发词 → 生成 record JSON → validate.py route 校验 → 通过即写入，不再人工确认。

② 隐式自动（该记的时候自己记，无需用户开口）：
- 干完一个待办收口 → summary 的 sunk_to 声明沉淀去向（必过 route 校验）
- 踩坑 → 当场记经验沉淀
- 架构 / 数据模型 / 代码入口变化 → 更新系统说明书
- 部署 / 配置 / 账号变化 → 更新部署运维手册
- 每轮收工 → 更新记忆管理的状态与断点

自动路由（用户不用指定落点）：信息落到哪个文档哪个章节，由「本质 essence」决定——生成 record JSON（content + essence + target + trigger + reason）→ python scripts/validate.py route 校验 essence 与 target 必须匹配 schemas/routing.json 的既定落点 → 通过即写入 → audit 兜底管「形」。记错地方，结构上通不过；record 校验即弃（内容已进文档，不留过程工件）。

5.1 分层 + 槽位（5 份文档）

人读层（给人看，怎么用怎么维护）→ 放 docs/

AI 记忆层（给 AI 看，防失忆）→ 放 .onmyway/

5.2 自动路由契约（本质 → 落点）

信息按「本质 essence」自动路由到对应文档的对应章节，机器实现在 schemas/routing.json（唯一事实来源），validate.py route 强制 essence 与落点一致。15 类本质：

核心：按「本质」分流，不按「来源」；同一份信息只记一个地方，不重复；essence 判错属于语义层（机器拦不住），但「自判 essence 与落点自相矛盾」会被 route 打回。

5.3 六条护栏（四硬两软，机制见 5.5）

5.4 三道闸门（动文档前逐一自检，任一不过就不写）

5.5 硬约束（audit 文档审计：槽位 / 章节 / 上限 / 格式 / 汇总 / 凭证 / 索引 / 状态）

六条护栏中的 1/2/3/6 由 scripts/audit.py 机器执行——文档失控在结构上没有合法形态，自报数无效，全部实数对账。

机制链：文档结构契约（schemas/docs/*.json，与 templates/ 五份模板一一对应）→ python scripts/audit.py <项目根目录> 逐项审计 → 全绿才允许收口。

> 收口链完整顺序：cross 对账（4.4）→ 记入文档 → index.py 重建索引 → 文档审计（本节，含 F7）→ 回写需求文档状态。
> 模板与契约是一对：改模板必须同步改 schemas/docs/ 契约；契约外章节 = 自创 = 拦截。
> 诚实边界：G1 该不该写、结论制、语义查重仍是软约束——硬约束管「形」，「质」靠闸门自觉 + 人工审阅。

5.6 索引机制（AI 唤醒协议）

AI 唤醒第一步只读 .onmyway/index.md（检索地图），按需加载对应章节，禁止全量扫描 5 份文档。

• 触发：每次会话开始 / 切换 Agent / 会话压缩后 / 断点续传，先读 index.md 定位，再按需加载具体章节——token 成本降一个数量级。
• 索引内容（机器生成，纯机械，永不失真）：介入状态（来自 state.md 投影）+ 文档地图（路径/最后更新/章节列表/字数条数）+ 当前断点（进行中/未开始待办，来自需求文档状态表）+ dev-orders 清单。
• 生成：python scripts/index.py <项目根目录> 扫描文档生成 index.md；索引是「可再生派生物」，文档才是唯一事实来源，不靠 AI 手写维护。
• 新鲜度硬约束：index.md 生成时间早于任一文档/声明，audit F7 即打回收口（改了文档必须重建索引）。
• 跨设备：新 clone / 换设备后 mtime 被重置，先跑一次 index.py 重建，再读索引。

6. 记录风格（铁律）

<标签>：<一句话结论> —— 条目化、标签化、结论化。

• 一条信息一条记录，一句话说完，不写流水账
• 开头带「标签：」标明类型（约束 / 事实 / 状态 / 需求 / 规则 / 待办…）
• 只记结论，不记时间、编号、备选、理由、过程

> 关键认知：决策记录日志（ADR 的时间/编号/备选）对 AI 无意义。决策一旦定下来，立刻熔炼成一条原则或一个事实写进对应位置，然后忘掉过程。约束按「约束谁」分流——约束人/系统→系统说明书「系统红线」，约束 AI→记忆管理「约束」。

7. 文档命名与位置

项目根目录/
├── docs/                    ← 人读层
│   ├── 系统说明书.md
│   ├── 需求文档.md
│   └── 部署运维手册.md
└── .onmyway/                ← AI 记忆层（跨 Agent 平台，非某工具专属）
    ├── state.md             ← 介入状态（介入中/未介入，介入开关，随 git 走）
    ├── index.md             ← 检索地图（机器生成，AI 唤醒第一步读，不计 5 槽位）
    ├── 记忆管理.md
    ├── 经验沉淀.md
    └── dev-orders/          ← 开发顺序声明（过程工件，JSON，不占文档槽位）
        └── REQ-xxx.json

更新时机：

8. 反模式（禁止行为）

• ❌ 同一个主题写多份文档（xxx-最终版.md、xxx-v2.md、xxx-探讨.md）
• ❌ 把对话内容、调试日志、错误堆栈原文贴进文档
• ❌ 在模板之外自创章节、自创表格列、自创编号规则
• ❌ 超过上限仍继续追加条目，而不做合并/淘汰
• ❌ 文档虚报计数：条目 / 字数 / 总计行与实际不符（audit 实数对账，必打回）
• ❌ 把凭证（生产密码/token/私钥）明文写进文档（测试账号除外，只记位置）
• ❌ 未经用户同意新建第 6 类文档
• ❌ 写经验前不查重，重复记同类经验
• ❌ 问问题时零散追着小问题问、直接抛细节不带全局定位
• ❌ 把 AI 的思考过程、上下文、中间结论写进人读层（过程信息只进 AI 记忆层）
• ❌ 记决策过程（时间线 / 编号 / 备选对比 / 理由链）而不熔炼成一条结论
• ❌ 走完流程就宣称完成（交付必须过校验、代码必须逐层真实验证，流程表演不算数）
• ❌ 多任务混装：多个需求打包一份声明、一份总结笼统收口、一句「都搞定了」带过（必须拆分、各自声明、分别汇报）
• ❌ 不过依赖三查就开工：上游没就绪、下游影响没盘清（尤其数据类改动）、开工条件不齐——闷头就干
• ❌ 改了文档不重建索引（index.py），导致 index.md 陈旧误导后续检索（audit F7 必打回）
• ❌ 唤醒后全量扫描 5 份文档（应先读 .onmyway/index.md 检索地图，按需加载）
• ❌ 介入中（state.md=介入中）却跳过主循环 / 硬约束，或退出后仍强制走方法论

9. 安装 / 部署

本技能面向通用 Agent 平台（纯 Markdown + JSON + Python，不绑任何特定工具）：

• 技能目录方式：将本目录整体复制进所用 Agent 的 skill / 规则加载路径（各家叫法不同：skills、rules 等）
• 规则文件方式：将本 SKILL.md 内容并入系统提示词 / AGENTS.md / CLAUDE.md 等规则文件，templates/ 与 schemas/ 留在项目内供引用
• 在某项目启用后，AI 会在该项目根目录自动维护 docs/（人读层）与 .onmyway/（AI 记忆层）；.onmyway/ 随 git 走，跨 Agent、跨会话、跨设备同步。
• 收口前对项目跑 python scripts/audit.py <项目根目录> 完成文档审计（F1–F8），全绿才允许回写待办状态；文档结构契约在 schemas/docs/，与模板一一对应，改模板必须同步改契约。
• 每次收口（改文档后）先跑 python scripts/index.py <项目根目录> 重建 .onmyway/index.md 检索地图，再跑 audit 通过 F7 新鲜度检查；新 clone / 换设备后先重建索引再读。