reflect

阶段门：COMMIT 检查点。在第 8 步通过之前，不要宣布任务完成。

按顺序执行所有步骤。仅在明确的升级节点向用户求助。

步骤 0 — 标记反思时间戳

date +%s > "${CLAUDE_PROJECT_DIR}/ai-workspace/.last-reflect-ts"

步骤 1 — 回顾会话中的工作

git log --oneline -10

回顾本次会话期间所做的近期编辑和更正。如果 ai-workspace/plans/ 中有已完成的计划（“成果与经验”已填写），则以此为主要依据。否则，直接从 git 历史和会话事件中总结经验。继续之前，明确列出候选经验清单。

步骤 1b — 验证问题是否已关闭

扫描提交消息，查找后面跟着 #N 的关闭关键词（不区分大小写）：closes、close、closed、fixes、fix、fixed、resolves、resolve、resolved。

对找到的每个问题编号：

gh issue view N --json state --jq '.state'

如果引用的问题仍处于打开状态，则发出警告。不要因此阻止流程，继续执行。

步骤 2 — 对经验分类

信号	目标位置
涉及此仓库的文件、路径、配置或项目约定	仅写入 MEMORY.md
适用于多个项目的通用模式、工具行为或偏好	仅写入 Basic Memory 知识库
两者兼有（跨项目模式的项目特定实例）	两者都写入，并在每条记录中交叉引用另一条

步骤 2b — 在相关问题中评论经验

计划的 frontmatter 中有 Issue: #N：直接在该问题下发表评论，分享经验。无需确认——关联已明确。

没有计划或没有 Issue 字段：运行 gh issue list --state open --json number,title,labels --limit 50，将关键词与打开的问题标题进行模糊匹配。发布到任何模糊匹配的问题之前，先向用户确认。错误的自动评论比漏掉评论更糟。

步骤 3 — 写入 MEMORY.md（并发写入协议）

MEMORY.md 位于 main 分支，可能会收到并发写入。绝不要从当前工作树写入。

REFLECT_DIR="${CLAUDE_SESSION_DIR:-$TMPDIR}/memory-reflect"
[ -d "$REFLECT_DIR" ] && rm -rf "$REFLECT_DIR"
git clone --depth 50 "$(git remote get-url origin)" "$REFLECT_DIR"

重试循环（最多 3 次）：

1. 读取当前 $REFLECT_DIR/ai-workspace/MEMORY.md。
2. 根据当前文件内容重新推导记录——跳过已有内容，避免重复。不要自动合并，也不要重放旧差异。
3. 添加新记录。清理超过 30 天的记录。保持在 200 行以内——如果超出，则概述最旧的部分（绝不能悄悄删除）。
4. 提交并推送：

git -C "$REFLECT_DIR" add ai-workspace/MEMORY.md
git -C "$REFLECT_DIR" commit -m "reflect: update MEMORY.md [$(date +%Y-%m-%d)]

Co-Authored-By: Claude <model>"
git -C "$REFLECT_DIR" push

5. 如果因非快进更新而被拒绝：运行 git -C "$REFLECT_DIR" pull --rebase，然后返回第 1 步。
6. 失败 3 次后，停止并升级处理——不要继续：

   MEMORY.md 写入在重试 3 次后仍失败。需要手动合并 $REFLECT_DIR/ai-workspace/MEMORY.md。

同步到主工作树

成功推送后，将主工作树的 main 更新到最新状态，以便其他 Agent 立即看到新的 MEMORY.md：

PRIMARY="$(git worktree list --porcelain | grep -m1 '^worktree ' | sed 's/^worktree //')"
CURRENT=$(git -C "$PRIMARY" branch --show-current)
if [ "$CURRENT" = "main" ]; then
  # WIP commit if dirty
  if [ -n "$(git -C "$PRIMARY" status --porcelain)" ]; then
    git -C "$PRIMARY" add -u
    git -C "$PRIMARY" commit -m "wip: preserve local state before reflect sync"
    WIP=1
  fi
  git -C "$PRIMARY" fetch origin main
  git -C "$PRIMARY" merge --ff-only origin/main || echo "Primary diverged — manual pull needed"
  # Restore WIP
  [ "${WIP:-}" = "1" ] && git -C "$PRIMARY" reset --soft HEAD~1
fi

如果主工作树不在 main 分支，则跳过同步——后续的 git pull 会获取更新。

步骤 4 — 写入 Basic Memory 知识库

先使用 mcp__basic-memory__search_notes 避免重复，然后使用 mcp__basic-memory__write_note 或 mcp__basic-memory__edit_note。使用 [[wiki-links]] 建立关联。每条记录都标记当前项目名称。

如果 Basic Memory MCP 未连接，则在输出摘要中记录跳过此步骤，并继续。不要因此阻止流程。

步骤 5 — ADR 检查

如果出现了重要的架构决策、约定或反复出现的模式，请询问：

这是否应成为一份 ADR？候选内容：“<模式摘要>”。（y/n）

如果是：使用 ai-workspace/decisions/TEMPLATE.md 中的模板创建 ai-workspace/decisions/ADR-NNN-<slug>.md。使用现有最高 ADR 编号加一。

步骤 6 — 根据发现的工作创建问题

先检查是否存在重复问题（打开的问题和近期已关闭的问题）：

gh issue list --state open --limit 100 --json number,title
gh issue list --state closed --limit 20 --json number,title

来源 (a) — 反思 TODO：第 1–5 步中发现的注意事项、后续工作和技术债务。对每项没有重复问题的内容创建一个 GitHub 问题。

来源 (b) — 暂存笔记（ai-workspace/scratchpad.md）：对每行匹配 - [ ] ... 的内容 → 创建问题 → 改写为 - [x] → #N。保持普通项目符号不变——它们是参考笔记。

第 7 步 — 完成计划

将当前计划重命名为 .done.md。先确认已填写「成果与经验」。

mv ai-workspace/plans/<name>.md ai-workspace/plans/<name>.done.md

此提交可以提交到主工作树 — .done.md 计划文件在允许列表中（参见 task-branches.md）。如果没有当前计划，则跳过。

第 8 步 — 阶段门控

阅读 .branch-context.md：

• MEMORY.md 未更新 + .branch-context.md 有内容 → 软性阻止：发出警告，在问题解决前不要宣布任务完成。
• .branch-context.md 缺失或为空 → 发出警告，但不阻止。

输出摘要

层级	操作
MEMORY.md	新增 N 条，清理 N 条（共 X 行）
Basic Memory	写入/更新 N 条笔记（或：已跳过 — MCP 不可用）
已关闭的问题	#N、#N（已验证）/ #N 仍未关闭（已警告）
已创建的问题	#N「」、#N「<title>」
已评论的问题	#N
ADR	已创建 ADR-NNN / 已跳过
计划	已完成 .done.md / 无
阶段门控	MEMORY.md 已更新：是/否 — .branch-context.md：找到/缺失