session-close

/session-close -- 会话到记忆的对账

将当前会话中持久有效的成果对账并写入项目记忆文件。这是状态对账，不是会话日志记录——输出应当与人类在一周工作后更新项目记忆的内容别无二致。

核心原则

代码记录成果；记忆记录推理。 Git 已经记录了哪些内容发生了变化。项目记忆文件用于记录为何做出决策、项目的当前状态以及接下来要做什么——这些信息无法从差异中推导出来。

此技能旨在避免的反模式

像 project_session_apr8_9.md 这样的文件——将一个会话中跨多个项目完成的所有工作不加整理地堆在一起。这类文件无法通过“新团队成员”测试：明天加入的开发者无法区分重要信息和噪声。状态对账生成的文件应回答“这个项目是什么？”，而不是“今天发生了什么？”

参数

• 参数 1（可选）： 要更新的项目名称。如果省略，此技能会根据对话上下文和工作目录识别项目。

流程

阶段 1：识别——涉及了哪些项目？

通过以下三个来源，确定本次会话中有哪些项目完成了有意义的工作：

1. 对话上下文（主要来源）。 查看当前对话，识别讨论过的项目。这是信息最丰富的来源——它能记录仅凭 Git 无法获知的意图、决策和成果。

2. 工作目录。 检查当前工作目录：

   • 如果 cwd 是项目目录（包含 .git/），则它是主要项目
   • 如果 cwd 是包含多个项目子目录的工作区，检查哪些目录近期有活动
   • 如果 cwd 是主目录（~/），则完全依赖对话上下文

3. Git 状态（验证）。 对于每个已识别的项目目录：

   # Cross-platform: works on macOS and Linux
   git -C $PROJECT log --oneline --since="12 hours ago" 2>/dev/null
   git -C $PROJECT status --porcelain 2>/dev/null  # uncommitted work
   

   Git 用于确认代码实际发生了哪些变化。如果对话提到了工作，但 Git 中没有任何变化，请标记这一差异。同时记录任何未提交的更改——务必将其纳入“状态”部分。

项目到记忆的映射： 动态解析记忆目录：

• Claude Code 将项目记忆存储在 ~/.claude/projects/<escaped-project-path>/memory/
• 转义路径会将 / 替换为 -（例如，/Users/alice/Projects/myapp 会变为 -Users-alice-Projects-myapp）
• 记忆文件遵循命名约定 project_{name}.md
• 如果项目已有记忆目录，则使用该目录；否则创建一个。

收敛规则： 项目必须同时出现在对话上下文和至少一个其他来源（Git 或 cwd）中，才会纳入处理。这可以避免为仅被提及的项目更新记忆。

阶段 2：读取——加载现有项目记忆

对于每个已识别的项目：

1. 从解析出的记忆目录中读取项目记忆文件（project_{name}.md）
2. 解析其结构：前置元数据、章节标题和内容
3. 如果文件不存在，请记录下来——之后将参照现有模板创建新文件
4. 大小检查： 统计行数。如果超过 80 行，请标记，以便在对账期间考虑精简。MEMORY.md 会从所有文件中加载前 200 行——臃肿的项目文件会挤占其他记忆。

还要读取：

• MEMORY.md 索引（检查是否需要更新索引）
• 如果需要了解技术栈或架构背景，则读取项目的 CLAUDE.md

阶段 3：提取——对会话事件分类并筛选

回顾对话和 Git 历史。对于每个重要事件，进行分类：

类型	是否持久化？	示例
DECISION	始终	“将认证方式从会话 Cookie 切换为 JWT”
STATUS_CHANGE	始终	“晋升至预发布环境”、“已部署到生产环境”
DISCOVERY	如果有新发现	“发现 Neon 免费套餐的连接数上限为 100”
IMPLEMENTATION	仅记录结果	“构建了 MCP 服务”（而非“在 src/mcp/ 中创建了 12 个文件”）
TROUBLESHOOTING	仅记录规律	“文件大于 4.5 MB 时需要 Vercel Blob”（而非 5 个调试步骤）
EXPLORATION	从不	阅读文档、搜索代码、尝试后放弃的方法

然后应用三道筛选关——每项都必须全部通过：

1. **持久性：**30 天后，这条信息是否仍然属实或相关？

   • 是：架构决策、已发布的功能、配置更改、部署状态
   • 否：调试步骤、错误消息、中间尝试、运行过的命令

2. **具体性：**我能否将其表述为包含主语、动词和具体值的明确陈述？

   • 是：“从 HyTek MDB 文件导入了 457K 条游泳成绩”
   • 否：“处理了导入系统”

3. **可检索性：**未来的会话是否可能需要这条信息？

   • 是：约束、约定、有理由的决策、集成细节
   • 否：我们如何发现某事、读过哪些文件、按什么顺序尝试过哪些方法

对于通过全部三道筛选关的项目，记录：

• 变更内容（具体事实）
• 变更原因（背后的理由——这是代码本身无法说明的）
• 影响范围（对下游的影响）

阶段 3.5：按层归类（V2）——仓库与本地

本地记忆不适合存放仅克隆仓库的 Agent 或协作者需要的知识。2026 年的共识是分为三层：约定 → CLAUDE.md/AGENTS.md、决策及理由 → 仓库的 docs/decisions/（ADR）、当前状态/后续事项 → docs/PROJECT_STATUS.md——而本地记忆只保留剩余内容（个人草稿、密钥位置、跨项目备注）。持久化每条长期有效的信息之前，先确定它的归属：

项目	应存放于	操作
团队成员/远程 Agent 需要的决策及理由	仓库 ADR（docs/decisions/）	写入仓库；不要把理由埋在本地记忆中
约定/架构规则	CLAUDE.md / AGENTS.md	建议在相应文件中修改
当前状态/后续步骤	如果仓库使用 PROJECT_STATUS.md，则写入该文件；否则写入记忆中的 Status	按相应位置归类
密钥位置、个人/工具草稿、跨项目备注	仅本地记忆	保留（绝不提交）

这不是额外工作，而是把每条信息放到下一位读者真正会查找的地方。如果仓库尚未设置这些内容（没有 ADR / PROJECT_STATUS），请注明并建议创建这些已提交的文档；在此之前，以记忆作为备用位置。这样，记忆中就只保留真正没有仓库归属的信息。阶段 7 会处理本步骤识别出的 CLAUDE.md/AGENTS.md 项目——将它们交由 claude-md 审查，以便有针对性地纳入。

阶段 4：协调——按章节类型合并

对于每个项目记忆文件，根据其合并类型对各章节进行分类，然后采用相应策略：

REPLACE 章节（整体覆盖）

Status 章节（标题以 ## Status 开头）：

• 完全删除现有的 Status 区块
• 新建一个区块：## Status (Mon DD, YYYY)，包含 3-5 条要点
• 包含：当前分支、部署状态、关键指标、近期后续步骤
• **纳入未提交的工作：**如果 git status --porcelain 显示有变更，注明“工作树中有 N 个未提交文件”，以免下一次会话产生困惑
• 此章节始终整体覆盖——它反映的是当前状态，而非历史

MERGE-LIST 部分（去重、更新、追加）

待办事项（或同等部分：TODO、下一步、路线图）：

• 根据核心描述匹配现有条目（忽略复选框状态、日期和标签）
• 标记已完成的条目：将 - [ ] 改为 - [x]（保留以跟踪进度）
• 添加会话期间发现的新条目
• 如果会话揭示了新的优先级，则按优先级重新排序

功能部分（功能说明、特性、能力等）：

• 按实体名称匹配（例如，“MCP 服务”“SSE 流式传输”）
• 如果实体已存在：原位更新项目符号条目，注明最新状态
• 如果是新实体：追加到该部分
• 切勿重复已有信息

保留部分（仅在明确变更时修改）

技术栈、安全、参数、数据库、架构、配置（或同等部分）：

• 仅在会话明确变更了此类别的内容时才进行修改
• 如果未变更，保持该部分逐字节完全一致
• 切勿重新生成这些部分——大模型重写可能会微妙地丢失细节并改变语气

Frontmatter

• 仅当项目的一句话概述范围发生变化时，才更新 description（很少发生）
• 不要添加或更改 originSessionId

信息整合规则

1. 切勿重复已有信息
2. 更新事实时，找到已有陈述并原位编辑
3. 保留现有文件的语气和结构——不要重写未变更的文本
4. 如果不确定是否发生了变化，请保持现有文本不变
5. 新部分应遵循文件中既有的模式

第 5 阶段：呈现——展示变更以供批准

未向用户展示变更内容前，不要写入文件。

对于每个项目，清楚地总结拟议的变更：

## project_{name}.md -- Proposed Changes

### Status (full replace):
- [new status bullets]

### Backlog (N completed, M added):
- [x] Completed item (done Mon DD)
- [ ] NEW: New item description

### [Section Name] (N updates):
- Added: [item]
- Changed: [old] -> [new]

### Size: current NN lines -> proposed NN lines

然后询问：“应用这些变更吗？”

• 是——全部应用
• 编辑——允许用户在应用前修改
• 跳过 [project]——跳过特定项目

获得批准后，使用 Edit 工具对相应部分进行精确更新。对于 Status 部分，替换整个区块。切勿重写未发生变更的部分。

第 6 阶段：建立索引——更新 MEMORY.md

如果创建了任何新的记忆文件：

1. 在 MEMORY.md 的 ## Projects 部分添加一条记录
2. 遵循现有格式：- [Project Name](memory/project_name.md) -- one-line description
3. 保持该部分中的字母顺序
4. **行数检查：**如果 MEMORY.md 超过 180 行，请提醒用户它正接近 200 行的上下文加载上限

阶段 7：CLAUDE.md 审查——提升跨 Agent 经验（可选；需要 claude-md 技能）

记忆记录了本次会话中的推理过程。但阶段 3.5 归纳的内容中，有些并不属于记忆的职责——它们是每个 Agent 和队友都需要了解的约定或架构规则，应写入已提交的 CLAUDE.md/AGENTS.md：这是跨 Agent 层，新克隆的项目或其他 Agent 会首先读取这里。只留在本地记忆中的经验对他们不可见，而且有人重新运行 /init 时就会悄无声息地丢失。

对于每个已修改且拥有（或应当拥有）CLAUDE.md / AGENTS.md 的项目：

1. 收集值得写入 CLAUDE.md 的内容：整理阶段 3.5 中浮现的约定、架构规则、“始终/绝不”指导，以及本次会话中新出现、其他 Agent 也需要了解的内容。（如果阶段 3.5 没有发现此类内容，则跳过本阶段。）
2. 如果已安装 claude-md，则交由它处理（它与此技能一同提供于 ngmeyer/skills）：运行 /claude-md audit（检查所有 CLAUDE.md 文件中的偏离、泄露的机密和冗余内容），或运行 /claude-md improve <path>（根据最佳实践评估单个文件，并提出精准的差异修改），并将第 1 步整理的内容提供给它。claude-md 会在每项差异修改前征求你的批准。
3. **如果没有 claude-md，则妥善降级处理：**打印这些内容——"本次会话中有 N 条约定可能适合写入 CLAUDE.md；请安装 claude-md 或手动添加"——确保不会遗漏。绝不要因此阻塞流程。

绝不要运行 /init 来更新现有的 CLAUDE.md。 /init 会重新生成整个文件：它会凭空添加架构章节，并丢弃那些经过精心整理、来之不易却尚未写入文件的经验。本阶段的目标是精准提升（只添加值得保留的少数几行，其余内容逐字节保持不变），而不是重新生成。如果项目还没有 CLAUDE.md，建议创建一个精简版本——不要自动生成冗长文件。

这是一个有意设计的软依赖——如果没有 claude-md，流程会降级为打印列表，因此即使只安装了部分技能，会话收尾流程也能独立运行。

阶段 8：清理——提议移除产物

检查并提议删除：

1. ~/.claude/plans/ 中所有任务均已完成的会话专属计划文件
2. 内容已整合到各项目文件中的会话转储记忆文件（例如 project_session_*.md）
3. ~/.claude/tasks/ 中所有任务的状态均为 completed 的已完成任务目录
4. 其他项目文件中过时的 Status 章节：如果项目文件中的 Status 章节日期距今超过 30 天，则标记出来供审查

删除前务必先询问。 列出清理项并等待确认。

注意事项

• 不要转储会话。 切勿创建 project_session_*.md 文件——这正是该技能旨在防止的反模式
• 不要采用会话叙述方式。 切勿写“在 4 月 11 日的会话中，我们……”，应记录状态，而非历史
• 不要写实现细节。 除非属于架构层面的关键节点，否则不要包含文件路径、行号或函数名。代码记录成果；记忆记录推理过程
• 不要静默写入。 修改记忆文件前，务必展示差异预览并征得批准
• 不要强行更新。 如果会话没有产生任何持久成果（例如纯调试、研究或后来放弃的探索），请报告“No durable state changes detected”并退出
• 不要扩大范围。 仅更新 project_*.md 文件——不要触碰反馈、用户或参考记忆文件
• 不要进行远程调用。 不要从 git 远程仓库获取内容，也不要发起网络请求。仅使用本地状态
• 不要记录不存在的项目。 不要为仅被提及、但未实际开展工作的项目创建记忆
• 能力或技术栈部分不要添加带日期的条目。 日期只应出现在状态部分
• 不要重新生成部分内容。 切勿重写未更改的部分。LLM 重写会悄然丢失细节、改变语气并引入偏差。使用 Edit 工具修改特定行，不要用 Write 重写整个文件
• 不要写含糊的总结。 “改进了身份验证”不符合具体性要求。每条持久化事实都必须包含明确的主语、动词和具体内容
• 绝不要使用 /init 刷新现有的 CLAUDE.md。 它会重新生成整个文件，并丢失仅保存在记忆中的精心整理的经验。应通过 claude-md 技能（第 7 阶段）有针对性地纳入 CLAUDE.md，切勿重新生成。记忆用于推理；CLAUDE.md/AGENTS.md 是跨 Agent 的约定层——各司其职

章节命名约定

协调逻辑会根据以下模式匹配章节。记忆文件应使用这些标题（或相近的标题）：

合并类型	章节标题（灵活匹配）
REPLACE	## Status、## Current Status
MERGE-LIST	## Backlog、## TODO、## Next Steps、## Roadmap、## What It Does、## Features、## Capabilities
PRESERVE	## Stack、## Architecture、## Safety、## Config、## Parameters、## Database

不符合任何模式的章节将被视为 PRESERVE（安全默认值）。

边缘情况

没有现有记忆文件： 根据现有项目文件的模板创建新文件（frontmatter + What It Does、Stack、Status、Backlog 章节）。提交完整的新文件供审批。

没有持久成果： 报告“No durable state changes detected for any project. Nothing to update.”并正常退出。对于调试会话、研究或阅读会话，或已放弃的探索，这才是正确做法。不要强行更新。

信息冲突： 向用户标明对话内容与 git 记录之间的冲突。例如：“对话中提到了部署到 Fly.io，但没有找到部署提交。是否将此内容纳入状态更新？”

在主目录中开展的多项目会话： 分别处理每个项目。这正是避免会话转储反模式的做法。

超大型会话（4 小时以上）： 依次处理各个项目，不要一次性全部处理。每次只展示一个项目的更改。

更新后文件超过 80 行： 提醒用户，并建议删除已完成的待办事项或精简冗长章节。项目文件应保持精简——它们会占用 MEMORY.md 200 行的上下文预算。

检测到未提交的工作： 务必将其纳入 Status 部分。之前的会话曾遗漏未提交的工作，导致后续会话产生困惑。

更新日志

V2.1 (2026-06-11) -- CLAUDE.md 审计交接（阶段 7）

新增 阶段 7：CLAUDE.md 审计。整理完记忆后，将阶段 3.5 识别出的跨 Agent 约定纳入已提交的 CLAUDE.md/AGENTS.md，交由 claude-md 技能通过精细且需审批的 audit/improve 完成——绝不要使用 /init，因为它会重新生成文件，并丢弃只存在于记忆中的精选经验。至此，阶段 3.5 开启的闭环得以完成：它识别出了值得写入 CLAUDE.md 的事项，却没有任何操作落实它们。软依赖——如果未安装 claude-md，则降级为打印列表，确保会话收尾流程完整自洽；这两项技能都由 ngmeyer/skills 提供，因此引用同级技能是安全的。CLEANUP 编号从 7 调整为 8。

V2 (2026-05-27)

通过 skillforge optimize 优化（成果研究：AI Agent 记忆 / 上下文工程，2026）。

• 阶段 3.5 按层分流 — 将持久性内容送到合适的位置（约定→CLAUDE.md/AGENTS.md，决策→仓库 ADR，状态→PROJECT_STATUS），而不是默认一股脑塞进本地记忆；记忆只保留剩余内容。这种三层划分是 2026 年工程领域的共识。
• 在现有的“不是倾倒信息”/大小检查规则基础上，补充文档中说明的原因：上下文腐化（记忆不断膨胀会导致质量下降），而选择性记忆的成本约为臃肿上下文的 1/10 至 1/20。
• 成果目标：恢复工作所需的关键信息应放在任何 Agent 或队友都能找到的地方，而不是孤立在某台机器的本地记忆中。来源：State of AI Agent Memory 2026 (mem0)；Agent Memory vs Context Engineering (Augment)。

致谢

技能作者：Neal Meyer