📝 docs(memory): bound context snapshot sections

templates/AGENT_RULES.template.md

@@ -263,7 +263,10 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
 - 待确认事项在回复中显式列出
 - `workflow-state` 和 `plan-status` 只能通过
   `{{PLAYBOOK_SCRIPTS}}/main_loop.py` 维护
-- `progress.md` 上半部分的人类摘要在阶段变化或执行结束后同步更新
+- `progress.md` 上半部分是短期状态快照，不是 changelog；
+  阶段变化或执行结束后整理/替换摘要，不做无限追加
+- `active-context.md` 是短期上下文快照，不是长期日志；
+  只保留当前 Plan / 下一轮仍重要的目标、变化、文件与下一步
 - 同一错误重复两次以上时，立即更新
   `AGENT_RULES.local.md` 或 `memory-bank/decisions.md`
 - 发现项目特有规律时，沉淀到 `AGENT_RULES.local.md`

templates/memory-bank/active-context.template.md

@@ -3,7 +3,12 @@
 <!--
 填写指南：
 - 本文件记录高频变化的上下文，供 AI 在跨 Session 时快速恢复工作状态
+- 本文件是短期上下文快照，不是长期日志
 - 保持简洁，只写“现在仍然重要”的信息
+- `Recent Changes` 只保留最近 3-5 条仍影响后续判断的变化
+- `Touched Files` 只保留当前 Plan / 下一轮仍相关的文件
+- `Next Steps` 只保留接下来最优先的 1-3 步
+- 更新时整理/替换旧上下文，不做无限追加
 - 任务完成或方向切换后及时更新
 -->
 

templates/memory-bank/progress.template.md

@@ -3,6 +3,9 @@
 <!--
 填写指南：
 - 上半部分给人类和 AI 快速恢复上下文
+- 上半部分是短期状态快照，不是 changelog
+- `Recent Changes` 只保留最近 3-5 条对恢复上下文有价值的变化
+- 更新摘要时整理/替换旧摘要，不做无限追加
 - 中间的 workflow-state 块记录当前阶段、spec、plan 与执行约束
 - 下半部分的 plan-status 块由 main_loop.py 维护，是唯一权威状态源
 -->

templates/prompts/coding/update-memory.template.md

@@ -27,12 +27,20 @@
 - 最近变更
 - touched files
 - 下一步
+- 本文件是短期上下文快照，不是长期日志
+- `Recent Changes` 只保留最近 3-5 条仍影响后续判断的变化
+- `Touched Files` 只保留当前 Plan / 下一轮仍相关的文件
+- `Next Steps` 只保留接下来最优先的 1-3 步
+- 更新时整理/替换旧上下文，不做无限追加
 
 ### `memory-bank/progress.md`
 
 - 先读取 `workflow-state`：当前阶段、spec、plan、executor、constraints
 - 再读取 `plan-status`：当前 Plan 的机器状态
 - 只更新上半部分的人类摘要，不修改状态块
+- 上半部分是短期状态快照，不是长期日志
+- `Recent Changes` 只保留最近 3-5 条对恢复上下文有价值的变化
+- 更新时整理/替换旧摘要，不要把 `Recent Changes` 当作无限追加日志
 
 ### `memory-bank/decisions.md`
 
@@ -55,6 +63,8 @@
 - 流程规则或项目私有约束变更写入 `AGENT_RULES.local.md`
 - `progress.md` 的状态块只由 `main_loop.py` 维护
 - 摘要应与 `workflow-state` / `plan-status` 保持一致
+- 摘要区保持短期状态快照；长期历史依赖 commit、Plan 文件和
+  `decisions.md`
 
 ## 禁止事项
 

tests/test_sync_templates_placeholders.py

@@ -62,6 +62,24 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase):
         ).read_text(encoding="utf-8")
         self.assertIn("## 成功定义", project_brief_template)
 
+        progress_template = (
+            ROOT / "templates" / "memory-bank" / "progress.template.md"
+        ).read_text(encoding="utf-8")
+        self.assertIn("短期状态快照，不是 changelog", progress_template)
+        self.assertIn("`Recent Changes` 只保留最近 3-5 条", progress_template)
+        self.assertIn("整理/替换旧摘要，不做无限追加", progress_template)
+
+        active_context_template = (
+            ROOT / "templates" / "memory-bank" / "active-context.template.md"
+        ).read_text(encoding="utf-8")
+        self.assertIn("短期上下文快照，不是长期日志", active_context_template)
+        self.assertIn("`Recent Changes` 只保留最近 3-5 条", active_context_template)
+        self.assertIn(
+            "`Touched Files` 只保留当前 Plan / 下一轮仍相关的文件",
+            active_context_template,
+        )
+        self.assertIn("整理/替换旧上下文，不做无限追加", active_context_template)
+
         update_memory_template = (
             ROOT / "templates" / "prompts" / "coding" / "update-memory.template.md"
         ).read_text(encoding="utf-8")
@@ -71,6 +89,15 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase):
         self.assertIn("## New Context", update_memory_template)
         self.assertIn("## Outstanding Risks", update_memory_template)
         self.assertIn("AGENT_RULES.local.md", update_memory_template)
+        self.assertIn("短期状态快照", update_memory_template)
+        self.assertIn(
+            "不要把 `Recent Changes` 当作无限追加日志", update_memory_template
+        )
+        self.assertIn("短期上下文快照", update_memory_template)
+        self.assertIn(
+            "`Touched Files` 只保留当前 Plan / 下一轮仍相关的文件",
+            update_memory_template,
+        )
 
         close_task_template = (
             ROOT / "templates" / "prompts" / "coding" / "close-task.template.md"
@@ -154,6 +181,8 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase):
         self.assertIn("`memory-bank/progress.md`", rules_template)
         self.assertIn("必要 memory 更新", rules_template)
         self.assertIn("工作区保持干净后再领取下一个 Plan", rules_template)
+        self.assertIn("`progress.md` 上半部分是短期状态快照", rules_template)
+        self.assertIn("`active-context.md` 是短期上下文快照", rules_template)
 
     def test_sync_templates_replaces_playbook_scripts_without_main_language_support(
         self,