diff --git a/README.md b/README.md index 84691e0..c960c7c 100644 --- a/README.md +++ b/README.md @@ -28,14 +28,14 @@ npx -y skills add ssh://git@gitea.fjy8018.top:8022/fjy8018/coding-skills.git --s 本次保留现有接口格式。讨论资产放到 /绝对路径/工程讨论。 ``` -Agent 先调查再提问，纠正有证据的错误判断，每轮维护精简的当前决策。范围明显变大时，会提出分阶段建议供用户选择。关键问题解决后，先将完整计划写入文件并标为“待确认”，对话只给简短摘要和文件链接。用户自行读取文件审阅，确认后将该版本标为已批准。 +Agent 先调查再提问，纠正有证据的错误判断，每轮维护精简的当前决策。范围明显变大时，会提出分阶段建议供用户选择。关键问题解决后，先将完整计划写入文件并标为“待确认”，对话只给简短摘要和文件链接。用户自行读取文件审阅，确认后将该计划标为已批准。 计划列出修改文件、目标、原因和验收要求，不预写详细实现代码。核心算法可附少量代码或伪代码帮助审查；具体实现由执行 agent 在已批准的行为和架构边界内自主决定。 审阅确认后自行开启新会话，指定已批准的计划： ```text -使用 execute-plan 执行 /绝对路径/工程讨论/2026-09-10-pagination-fix/plan-v1.md +使用 execute-plan 执行 /绝对路径/工程讨论/2026-09-10-pagination-fix/plan.md ``` 支持命令式调用的宿主也可使用对应的 skill 命令，具体语法以宿主为准。Skill 不负责自动创建新会话，也不能保证检测或清除旧上下文。 @@ -50,18 +50,18 @@ Agent 先调查再提问，纠正有证据的错误判断，每轮维护精简 ```text 资产根目录/ - CONTEXT.md 跨计划的业务与设计约束及原因 + CONTEXT.md 当前业务与技术约束、适用模块 日期-计划主题/ current.md 当前目标、确认决策、约束与未决问题 - plan-v1.md 自包含计划，先待确认、审阅批准后冻结 + plan.md 最新自包含计划，原地修订、审阅确认 execution-日期时间.md 实施与验证记录 ``` -待确认计划可按反馈修改，并提供变化摘要与链接重新审阅；已批准计划的实质修订另存新版本，确认后再执行。完整计划默认只在文件中提供，写入成功不代表已批准。当前决策随讨论更新，不累计聊天全文；执行记录不能覆盖已批准计划。目录失效或无法写入时会报告，不自行改存代码库。个人绝对路径不写入可分发的 skill。 +每个计划目录只维护 plan.md，修订直接覆盖，只保留最新方案，不生成版本副本或历史方案。实质修订清除旧批准依据并标为待确认，用户重新审阅后再执行。对话只给摘要和链接，写入成功不代表批准。current.md 同样只维护当前讨论状态，不累计历史。目录失效或无法写入时会报告，不自行改存代码库。个人绝对路径不写入可分发的 skill。 两个 skill 在确定资产根目录后都先读取 `CONTEXT.md`，再针对本次目标核实相关代码；新会话或上下文恢复时同样读取，无需扫描历史计划。根目录默认对应一个系统；若文档属于其他系统，先澄清。用户只指定计划目录时，保留已知系统根目录，未知则询问，不推断父目录。 -`CONTEXT.md` 按业务约束、设计约束记录长期决策、适用范围和简短原因。用户确认后立即沉淀，分为“当前有效”和“已确认待生效”；需要实施的约束经实施、验证和 review 完成后才生效，失败或部分完成时保留待生效状态。存在冲突时先确认如何修订，不自行覆盖。 +`CONTEXT.md` 只描述当前有效的业务约束和技术约束，可注明适用模块及必要原因。无需实施的已确认规则直接更新；依赖改造的方案暂留在讨论和计划中，经实施、验证和 review 完成后再更新 CONTEXT。冲突先确认，替换时删除废弃规则，不保存中间决策、状态历史或关联历史计划路径。 该文件不记录任务清单、实现代码、日志或完整历史。`current.md` 保留本次讨论与未决问题；计划保留本次相关约束的快照，执行记录保存进度和证据。CONTEXT 不存在时从首次确认的长期约束开始建立，不回扫历史计划。执行 agent 的局部实现选择不自动变成系统约束。 @@ -75,9 +75,9 @@ Agent 先调查再提问，纠正有证据的错误判断，每轮维护精简 --- ``` -系统填写项目或系统名称，目标概括对应计划的目标，无法确定时留空。时间对应资产所依据的决策，使用用户当地日期。未确认草稿先记创建日期，正文标明待确认；确认后更新为确认日期。已批准计划保留原日期，新版本使用新确认日期；实施记录沿用计划决策日期，执行时间单独记录。纯进度或排版更新不改决策日期。 +系统填写项目或系统名称，目标概括对应计划的目标，无法确定时留空。时间对应资产所依据的决策，使用用户当地日期。未确认草稿先记创建日期，正文标明待确认；确认后更新为确认日期。计划重新批准后使用新确认日期；实施记录沿用计划决策日期，执行时间单独记录。纯进度或排版更新不改决策日期。 -CONTEXT 的目标填写“保存系统长期有效的业务与设计约束”，时间为最近一次确认系统决策的日期；仅变更生效状态不修改该日期。 +CONTEXT 的目标填写“保存系统当前业务与技术约束”，时间为最近一次确认系统决策的日期；普通排版更新不修改该日期。 ## 验证 @@ -91,7 +91,7 @@ npx skills add . --list 行为检查应使用真实 agent 在隔离项目中演练：目录首次询问与复用、错误假设纠正、长对话恢复、目标分阶段、批准前不实现、新会话交接、必要配套文件与范围扩展的区别、过期计划、测试覆盖与重复、已有用户修改及提交隔离。 -系统上下文还需检查：首次无 CONTEXT、下次直接读取、确认后立即记录、待生效与当前规则并存、冲突澄清、执行失败不生效、验证后生效、局部实现细节不写入系统约束。 +系统上下文还需检查：首次无 CONTEXT、下次直接读取、无实施依赖的确认规则直接记录、待实施方案只留计划、冲突澄清、执行失败不改当前约束、验证后替换废弃规则、局部实现细节不写入系统约束。 结构验证只能检查格式和可发现性；静态场景复核只能发现指令缺口。两者都不证明模型实际遵循工作流，实际行为需要另行记录演练证据。不要把文字规则当作宿主级权限隔离。 @@ -103,6 +103,6 @@ npx skills add . --list - [Superpowers](https://github.com/obra/superpowers)：参考 brainstorming 的确认边界、writing-plans 的文件与验证说明、executing-plans 的计划复核。 - [Matt Pocock Skills](https://github.com/mattpocock/skills)：参考 grill-me / grilling 的先调查事实、再讨论决策。这里限制每轮 1–3 问，以目标和验收收敛，不要求穷尽所有分支。 -另外参考 [domain-modeling](https://github.com/mattpocock/skills/blob/main/skills/engineering/domain-modeling/SKILL.md) 在讨论中持续沉淀的机制。上游 CONTEXT 限于术语表、设计决策另存 ADR；本项目按需要将长期业务与设计约束直接保存在外部 CONTEXT，不引入 ADR 框架。 +另外参考 [domain-modeling](https://github.com/mattpocock/skills/blob/main/skills/engineering/domain-modeling/SKILL.md) 在讨论中持续沉淀的机制。上游 CONTEXT 限于术语表、设计决策另存 ADR；本项目按需要将当前业务与技术约束直接保存在外部 CONTEXT，不引入 ADR 框架。 上游工作流会变化；本仓库的实际规则以两个 `SKILL.md` 为准。 diff --git a/skills/align-plan/SKILL.md b/skills/align-plan/SKILL.md index 30aa5be..364aa3f 100644 --- a/skills/align-plan/SKILL.md +++ b/skills/align-plan/SKILL.md @@ -24,14 +24,14 @@ description: 通过调查和多轮问答对齐工程目标，生成待审阅计 --- ``` -时间使用用户当地决策日期；草稿先记创建日期、确认后更新。批准版本保留日期，进度、排版及生效状态变化不改日期。 +时间使用用户当地决策日期；草稿先记创建日期、确认后更新，进度与排版不改日期。 ## 系统约束与讨论状态 先读根目录 `CONTEXT.md`，再调查相关代码；不扫描历史计划。首次无 CONTEXT 时，从首条已确认长期约束开始创建。 -- `CONTEXT.md`：按业务、设计约束记录规则、适用范围、简短原因及状态。用户确认即更新；无需实施的规则为“当前有效”，依赖改造的为“已确认待生效”，可附计划位置。待生效规则不替代当前规则；冲突先展示影响并确认，生效后才移除失效规则。不放任务、代码、日志或局部实现偏好。目标为“保存系统长期有效的业务与设计约束”，时间为最近确认决策日期。 -- `<计划目录>/current.md`：每轮吸收回答后更新原始及当前目标、验收、确认决策与原因、事实来源、约束、不做事项、未确认假设和问题。替换失效决定，仅留必要的否决原因，不累计聊天全文。 +- `CONTEXT.md`：只按业务约束、技术约束记录当前有效规则，可注明适用模块及必要原因。确认且无需实施的约束直接更新；尚未生效的改造只留在当前讨论和计划中。冲突先确认，替换时删除废弃内容，不保留决策过程、历史计划路径、任务、代码、日志或局部实现偏好。目标为“保存系统当前业务与技术约束”，时间为最近确认决策日期。 +- `<计划目录>/current.md`：每轮更新目标、验收、确认决策与原因、事实来源、约束、不做事项、未确认假设和问题；删除失效内容，不累计讨论历史。 - 新会话、压缩恢复或出现矛盾时重读 CONTEXT、当前状态和相关代码；其余时候复用无变化内容。确认状态以真实回答为准，沉默和推荐都不算批准。 ## 调查与提问 @@ -44,9 +44,9 @@ description: 通过调查和多轮问答对齐工程目标，生成待审阅计 ## 写入、审阅与交接 -先写 `<计划目录>/plan-v1.md`，标为“待确认”。正文自包含，可合并章节，但须有： +只维护 `<计划目录>/plan.md`，先写入并标为“待确认”；修订覆盖同一文件，只描述最新方案，不保留版本副本、旧方案或变更历史。正文自包含，可合并章节，但须有： -1. **定位**：项目及必要仓库标识、资产根目录与 CONTEXT 绝对路径、Git 基线（无提交则注明）、相关工作区变化、版本与确认状态/依据。 +1. **定位**：项目及必要仓库标识、资产根目录与 CONTEXT 绝对路径、Git 基线（无提交则注明）、相关工作区变化、确认状态/依据。 2. **目标与决策**：原始目标、当前/目标行为、保留行为、不做事项；决策理由、业务/接口/架构变化或不变；相关系统约束快照及状态、已确认假设。 3. **修改范围**：新增/修改/删除的文件、各自目标和原因、必要依赖顺序及对应验收。允许必要测试/配置配套文件并记录，其他范围变化重新确认。 4. **验证**：验收条件、对应测试、运行目录/命令/预期结果与必要环境。 @@ -55,6 +55,6 @@ description: 通过调查和多轮问答对齐工程目标，生成待审阅计 写完重读，检查遗漏、矛盾及隐含决策；缺关键决定则继续提问。确认文件可读后，对话只给目标、范围、重要影响与验证摘要，以及文件绝对路径链接，供用户阅读确认；除非用户要求，不贴全文。 -用户确认该文件当前版本后，记录批准依据及日期并冻结。反馈先修改待确认文件，再给变化摘要与链接；已批准版本的实质修订另存待确认新版本。写入或摘要不代表批准。 +用户确认当前文件内容后记录批准依据与日期。实质修订直接更新 plan.md，清除旧批准依据并重置为待确认，再给摘要与链接；重新确认前不执行变化。写入或摘要不代表批准。 -确认后给出新会话提示：`使用 execute-plan 执行 /绝对路径/plan-v1.md`，结束规划。不要自动实施或声称已清空上下文。 +确认后给出新会话提示：`使用 execute-plan 执行 /绝对路径/plan.md`，结束规划。不要自动实施或声称已清空上下文。 diff --git a/skills/execute-plan/SKILL.md b/skills/execute-plan/SKILL.md index 6b48e49..67703c2 100644 --- a/skills/execute-plan/SKILL.md +++ b/skills/execute-plan/SKILL.md @@ -29,17 +29,17 @@ description: 执行用户指定的已批准工程计划，验证目标与范围 --- ``` -执行记录沿用计划决策日期，执行时间另记正文；新批准版本用用户当地确认日期。进度与排版不改日期；旧元数据缺失不等于缺少批准，不编造日期或改写原批准内容。 +执行记录沿用计划决策日期，执行时间另记正文；计划重新批准后用用户当地确认日期。进度与排版不改日期；旧元数据缺失不等于缺少批准，不编造日期。 -- CONTEXT 只沉淀已确认的跨计划业务/设计规则、适用范围、简短原因及状态；确认即记，依赖实施的标“已确认待生效”，其他为“当前有效”。不放任务、代码、日志或 agent 自选的局部实现。目标为“保存系统长期有效的业务与设计约束”，时间为最近确认决策日期。 -- 对照 CONTEXT 与计划快照：无关更新继续，其他实质冲突展示影响并澄清。实施、验证及 review 完成后，重读 CONTEXT，仅将本次落实的约束改为有效并移除其替代的失效规则，保留其他计划内容；失败或部分完成不提前生效，状态更新不改决策日期。 +- CONTEXT 只记录已确认且当前有效的业务约束、技术约束，可注明适用模块及必要原因；不放待实施方案、废弃决策、历史计划路径、任务、代码或日志。目标为“保存系统当前业务与技术约束”，时间为最近确认决策日期。局部编码选择不提升为系统约束。 +- 对照 CONTEXT 与计划：无关更新继续，其他实质冲突先澄清。实施、验证及 review 完成后，重读 CONTEXT，用本次落实的约束替换失效规则，保留无关的有效约束；失败或部分完成不提前更新，不记录状态变迁或旧规则。 - 执行记录仅保留任务状态、配套文件及理由、关键验证命令/结果、阻塞与偏差，不粘贴完整工具日志。恢复会话或压缩后重读 CONTEXT、计划和执行状态；无变化时复用已读内容。 ## 实施边界 - 每项改动对应批准任务或验收；优先复用现有能力，自主决定具体代码及内部组织，不要求计划提供详细代码或逐字照抄算法示例。 - 可补必要测试/配置文件并说明对应验收；其他文件扩展、业务/接口/架构变化或依赖升级须先确认，不能包装为配套改动。无关发现只记录，不顺手修复或重构。 -- 需变更范围时先将补充计划或新版本写入文件并标待确认，对话只给变化摘要、原因及绝对路径链接。用户审阅批准后继续；不覆盖原批准计划。 +- 需变更范围时直接更新同一 plan.md，仅保留最新方案；清除旧批准依据并标待确认，对话只给摘要、原因及链接。用户重新批准后继续，不生成版本副本或历史方案，也不事后改计划掩盖越界。完成前重读文件，若内容已变而未重新批准，先澄清。 ## 验证、Review 与提交