feat: persist system constraints in root CONTEXT.md
This commit is contained in:
mujing
@@ -4,7 +4,7 @@
|
||||
|
||||
| Skill | 用途 | 产出 |
|
||||
| --- | --- | --- |
|
||||
| `align-plan` | 调查代码、每轮提问 1–3 个问题、核对假设并收敛范围 | 当前决策与用户确认后的可执行计划 |
|
||||
| `align-plan` | 调查代码、每轮提问 1–3 个问题、核对假设并收敛范围 | 系统约束、当前决策与用户确认后的可执行计划 |
|
||||
| `execute-plan` | 按已确认计划实施、验证、核对范围和 review | 外部实施记录与本地 Git commit |
|
||||
|
||||
## 安装
|
||||
@@ -50,6 +50,7 @@ Agent 先调查再提问，纠正有证据的错误判断，每轮维护精简
|
||||
|
||||
```text
|
||||
资产根目录/
|
||||
CONTEXT.md 跨计划的业务与设计约束及原因
|
||||
日期-计划主题/
|
||||
current.md 当前目标、确认决策、约束与未决问题
|
||||
plan-v1.md 已确认、自包含的计划
|
||||
@@ -58,6 +59,12 @@ Agent 先调查再提问，纠正有证据的错误判断，每轮维护精简
|
||||
|
||||
新的批准版本另存。当前决策随讨论更新，不累计聊天全文；执行记录不能覆盖已批准计划。目录失效或无法写入时会报告，不自行改存代码库。个人绝对路径不写入可分发的 skill。
|
||||
|
||||
两个 skill 在确定资产根目录后都先读取 `CONTEXT.md`，再针对本次目标核实相关代码；新会话或上下文恢复时同样读取，无需扫描历史计划。根目录默认对应一个系统；若文档属于其他系统，先澄清。用户只指定计划目录时，保留已知系统根目录，未知则询问，不推断父目录。
|
||||
|
||||
`CONTEXT.md` 按业务约束、设计约束记录长期决策、适用范围和简短原因。用户确认后立即沉淀，分为“当前有效”和“已确认待生效”；需要实施的约束经实施、验证和 review 完成后才生效，失败或部分完成时保留待生效状态。存在冲突时先确认如何修订，不自行覆盖。
|
||||
|
||||
该文件不记录任务清单、实现代码、日志或完整历史。`current.md` 保留本次讨论与未决问题；计划保留本次相关约束的快照，执行记录保存进度和证据。CONTEXT 不存在时从首次确认的长期约束开始建立，不回扫历史计划。执行 agent 的局部实现选择不自动变成系统约束。
|
||||
|
||||
每份生成的 Markdown 资产（包括本地 MEMORY）顶部保留以下 YAML 元数据：
|
||||
|
||||
```markdown
|
||||
@@ -70,6 +77,8 @@ Agent 先调查再提问，纠正有证据的错误判断，每轮维护精简
|
||||
|
||||
系统填写项目或系统名称，目标概括对应计划的目标，无法确定时留空。时间对应资产所依据的决策，使用用户当地日期。未确认草稿先记创建日期，正文标明待确认；确认后更新为确认日期。已批准计划保留原日期，新版本使用新确认日期；实施记录沿用计划决策日期，执行时间单独记录。纯进度或排版更新不改决策日期。
|
||||
|
||||
CONTEXT 的目标填写“保存系统长期有效的业务与设计约束”，时间为最近一次确认系统决策的日期；仅变更生效状态不修改该日期。
|
||||
|
||||
## 验证
|
||||
|
||||
结构检查：
|
||||
@@ -82,6 +91,8 @@ npx skills add . --list
|
||||
|
||||
行为检查应使用真实 agent 在隔离项目中演练：目录首次询问与复用、错误假设纠正、长对话恢复、目标分阶段、批准前不实现、新会话交接、必要配套文件与范围扩展的区别、过期计划、测试覆盖与重复、已有用户修改及提交隔离。
|
||||
|
||||
系统上下文还需检查：首次无 CONTEXT、下次直接读取、确认后立即记录、待生效与当前规则并存、冲突澄清、执行失败不生效、验证后生效、局部实现细节不写入系统约束。
|
||||
|
||||
结构验证只能检查格式和可发现性；静态场景复核只能发现指令缺口。两者都不证明模型实际遵循工作流，实际行为需要另行记录演练证据。不要把文字规则当作宿主级权限隔离。
|
||||
|
||||
## 参考来源
|
||||
@@ -92,4 +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 框架。
|
||||
|
||||
上游工作流会变化；本仓库的实际规则以两个 `SKILL.md` 为准。
|
||||
|
||||
@@ -11,7 +11,7 @@ description: 通过代码调查和每轮 1–3 个问题对齐工程目标，纠
|
||||
|
||||
1. 先读取项目约束、Git 状态和项目根目录的 `.agent/MEMORY.md`。优先采用用户本次明确指定的资产目录，否则复用 MEMORY 中的 `讨论资产目录`；已有会话中明确指定的位置也有效，不重复询问。
|
||||
2. 没有位置时，在首轮 1–3 个问题中询问外部资产根目录。等待期间可只读调查，不自行选择目录或把讨论写进项目代码目录。
|
||||
3. 用户给出位置后，解析为绝对路径，确认不在当前代码库内；若用户明确要求例外，遵从其选择。确认目录可用后记录到 MEMORY，保留其中其他内容。不可写或路径失效时说明具体问题，请用户提供可用位置，不静默回退。
|
||||
3. 用户给出位置后，解析为绝对路径，确认不在当前代码库内；若用户明确要求例外，遵从其选择。确认目录可用后记录到 MEMORY，保留其中其他内容。区分系统资产根目录与本次计划目录；只指定计划目录时保留已知根目录，未知则询问，不把计划目录当根目录或推断其父目录。不可写或路径失效时说明具体问题，请用户提供可用位置，不静默回退。
|
||||
4. MEMORY 只保存必要定位信息，例如：
|
||||
|
||||
```markdown
|
||||
@@ -21,7 +21,7 @@ description: 通过代码调查和每轮 1–3 个问题对齐工程目标，纠
|
||||
目标: 保存讨论资产位置
|
||||
---
|
||||
## 讨论资产
|
||||
- 讨论资产目录：/用户指定的绝对路径
|
||||
- 讨论资产目录：/用户指定的系统资产根目录
|
||||
```
|
||||
|
||||
写入前检查 MEMORY 是否被 Git 跟踪；已跟踪则说明与“不提交本地记忆”的冲突，先解决冲突，不自行取消跟踪。未跟踪时在 `git rev-parse --git-path info/exclude` 指向的本地排除文件中幂等加入 `/.agent/MEMORY.md`，不改共享 `.gitignore`。非 Git 项目仍保留本地记忆，并说明当前无法设置 Git 排除。
|
||||
@@ -31,6 +31,17 @@ description: 通过代码调查和每轮 1–3 个问题对齐工程目标，纠
|
||||
|
||||
宿主限制写入时，遵从限制，在对话中维护当前状态并明确尚未落盘；不要把未保存资产说成已保存。资产维护是规划阶段唯一的写入范围，不能开始项目实现。
|
||||
|
||||
## 跨计划系统约束
|
||||
|
||||
确定资产根目录后，先读取 `<资产根目录>/CONTEXT.md`，再针对当前目标调查代码。新会话及上下文恢复时同样读取，不通过遍历历史计划恢复系统约束。文档不能替代对本次相关代码的核实。默认一个根目录对应一个系统；已有 CONTEXT 属于其他系统时先澄清，不混写或另建项目层级。
|
||||
|
||||
- 没有 CONTEXT 时可继续调查，在首次有已确认的长期约束时创建，不扫描历史计划补齐、不凭推测编写。
|
||||
- 用户确认长期业务决策、业务约束或设计约束后立即更新，不等整份计划结束。未确认建议、假设和当前任务的问题留在 `current.md`。
|
||||
- 正文按“业务约束”和“设计约束”组织；每条记录约束、适用范围、简短原因及状态。无需实施即可成立的规则标为“当前有效”；依赖尚未完成改造的规则标为“已确认待生效”，可附对应计划位置。
|
||||
- 待生效的新规则不替代当前有效规则。新决策与现有约束冲突时，展示差异和影响，由用户确认保留、修订或替代；决策真正生效后再移除失效规则，避免并存矛盾。
|
||||
- CONTEXT 自身必须可独立理解，不放聊天、任务清单、详细代码、测试日志或完整决策历史。仅保留当前需要的约束与原因，不能把局部实现偏好提升为系统规则。
|
||||
- 顶部沿用 `系统`、`时间`、`目标` YAML 元数据；目标为“保存系统长期有效的业务与设计约束”。时间记录最近一次确认系统决策的日期，仅更新生效状态时不改日期。
|
||||
|
||||
## 调查与问答
|
||||
|
||||
- 先读相关代码、调用链、现有测试与项目约束，再提出问题。需要外部证据时，针对影响当前决策的开源实现或官方资料查证，记录链接、版本或提交以及相关结论；不进行无边界的生态调研。无法查证的内容标记为待验证。
|
||||
@@ -49,7 +60,7 @@ description: 通过代码调查和每轮 1–3 个问题对齐工程目标，纠
|
||||
- 已查明事实及来源；尚待确认的建议或假设单独列出。
|
||||
- 约束、保留行为、不做事项、未决问题。
|
||||
|
||||
用新决定替换已失效决定；被否决方案只保留防止重提所需的一句原因，不累积聊天全文。用户未回答、沉默或模型自己的推荐都不算确认。恢复会话、上下文压缩或出现矛盾时，重新读取当前决策和相关代码；不能从压缩摘要猜测确认状态。
|
||||
用新决定替换已失效决定；被否决方案只保留防止重提所需的一句原因，不累积聊天全文。用户未回答、沉默或模型自己的推荐都不算确认。恢复会话、上下文压缩或出现矛盾时，重新读取 CONTEXT、当前决策和相关代码；不能从压缩摘要猜测确认状态。
|
||||
|
||||
## 收敛、确认与交接
|
||||
|
||||
@@ -69,6 +80,7 @@ description: 通过代码调查和每轮 1–3 个问题对齐工程目标，纠
|
||||
|
||||
## 定位与确认
|
||||
- 项目：仓库绝对路径；有远程时附仓库标识
|
||||
- 资产根目录与 CONTEXT.md 的绝对路径
|
||||
- 基线：分支、提交；无初始提交则明确注明
|
||||
- 工作区：与计划相关的未提交变化
|
||||
- 版本：v1；状态：待确认 / 已确认；确认日期与确认依据
|
||||
@@ -79,6 +91,7 @@ description: 通过代码调查和每轮 1–3 个问题对齐工程目标，纠
|
||||
## 决策与影响
|
||||
已确认选择及原因；业务行为、公共接口、架构的前后变化。
|
||||
无变化的类别明确注明；必要事实来源；已确认的假设。
|
||||
保留本次相关的系统约束快照及生效状态，不能只给 CONTEXT 链接。
|
||||
|
||||
## 文件与步骤
|
||||
预计新增、修改、删除的仓库相对路径、修改目标与原因。
|
||||
|
||||
@@ -10,7 +10,7 @@ description: 在新会话中读取用户指定的已确认工程计划，按范
|
||||
## 开始前
|
||||
|
||||
1. 完整读取计划，提取原始目标、已批准行为、保留行为、文件范围、步骤和验收条件。未给路径且无法从本次明确引用确定时询问路径，不猜“最新计划”。
|
||||
2. 读取目标项目约束、相关代码和测试，核对项目定位、Git 基线与工作区。路径变化时通过仓库身份和内容确认，不仅凭同名目录执行。基线提交变化不必自动阻塞：调查是否影响计划成立的前提；存在实质冲突再澄清。
|
||||
2. 从计划定位信息或项目 `.agent/MEMORY.md` 确定系统资产根目录，先读取该目录的 `CONTEXT.md`，再读取目标项目约束、相关代码和测试。只给计划目录且根目录未知时询问，不推断父目录、不扫描历史计划。定位信息互相冲突或 CONTEXT 属于其他系统时先澄清。文件不存在时依靠自包含计划与代码核实，不凭空补系统约束。核对项目定位、Git 基线与工作区；路径变化时通过仓库身份和内容确认，不仅凭同名目录执行。基线提交变化不必自动阻塞：调查是否影响计划成立的前提；存在实质冲突再澄清。
|
||||
3. 检查计划的确认状态及依据；缺少批准、存在关键遗漏或当前代码使计划失效时，展示具体缺口并取得澄清。不得把“执行这个未完成的草稿”当作所有隐含决策都已确定，也不对已有有效批准重复索要确认。
|
||||
4. 记录实施前分支、HEAD（或尚无提交）、暂存、未暂存和未跟踪文件，保留足够的基线信息区分用户已有改动。不能覆盖、回退或替用户提交无关内容。若与任务重叠且无法可靠隔离，先解决冲突。
|
||||
5. 实施记录默认写在指定计划旁的独立 `execution-日期时间.md`，包含计划版本、基线、进度和证据，不覆盖已有记录。严格遵循用户指定位置：资产根目录下最多增加一层 `<日期-计划主题>/`，不插入项目名或系统名目录；用户已指定计划目录时直接使用。该位置必须符合用户的外部资产约定；位置不明时读取 `.agent/MEMORY.md` 或询问。目录不可用时报告问题，不回退到代码目录，不把资产混入 Git 提交。
|
||||
@@ -29,6 +29,13 @@ description: 在新会话中读取用户指定的已确认工程计划，按范
|
||||
|
||||
若当前会话还保留规划讨论，提醒用户新会话约定；不能假称已经清空上下文。无论宿主是否能识别会话边界，都以计划和重新读取的代码为依据。宿主处于只读或计划模式时遵从限制，不执行变更。
|
||||
|
||||
## 系统约束核对与维护
|
||||
|
||||
- 对比 CONTEXT 当前约束、待生效约束和计划中的约束快照。无关更新不阻塞执行；计划已明确批准从当前规则迁移到待生效规则时按计划实施。其他实质冲突先展示影响并澄清，不能机械认定文档或计划中某一份总是优先。
|
||||
- 只记录用户已确认、跨计划适用的业务与设计约束，确认后即可写入根目录 CONTEXT，依赖实施的规则标为“已确认待生效”。agent 自主决定的局部编码细节只属实现，不写成系统约束。
|
||||
- CONTEXT 按业务约束、设计约束组织，每条只保留约束、适用范围、简短原因和生效状态；不写任务清单、代码、执行日志或完整历史。沿用资产 YAML 格式，目标为“保存系统长期有效的业务与设计约束”，时间为最近一次确认系统决策的日期。
|
||||
- 本次实施、验证及 review 完成后，才将已落实的待生效约束标为“当前有效”，移除被其替代的失效规则。失败或部分完成时不提前标为有效。更新前重读 CONTEXT，保留其他计划的内容；仅更新生效状态不改决策日期，不改原批准计划。
|
||||
|
||||
## 实施边界
|
||||
|
||||
- 按计划依赖顺序推进；每项改动必须能解释为完成一个批准任务或验收条件。优先复用代码库、标准库和平台现有能力。
|
||||
@@ -37,7 +44,7 @@ description: 在新会话中读取用户指定的已确认工程计划，按范
|
||||
- 可补充达成已批准目标所必需的测试或配置文件，在实施记录中说明文件、原因及对应验收条件。文件扩展不能成为更改业务行为、公共接口、架构、升级依赖或扩大验收范围的借口。
|
||||
- 其他未计划的文件改动或实质范围变化，先展示所需变化与原因，取得确认后保存补充计划或新版本，再继续受影响工作。保留原批准版本，不为解释已发生的越界改动而重写计划。
|
||||
- 发现无关问题时只在记录中注明“本次未处理”；不要顺手重构、清理、格式化整个仓库或修复旁支问题。
|
||||
- 记录任务进度、必要配套文件、验证命令和结果。恢复会话或上下文压缩后重新读取原计划与实施记录，不从聊天印象续做。
|
||||
- 记录任务进度、必要配套文件、验证命令和结果。恢复会话或上下文压缩后重新读取 CONTEXT、原计划与实施记录，不从聊天印象续做。
|
||||
|
||||
## 验证与 Review
|
||||
|
||||
|
||||
Reference in New Issue
Block a user