用途
agent-memory 用于管理 AI Agent 的记忆文件，创建、同步或精简项目根目录下的 AGENTS.md 与 CLAUDE.md。其定位是维护代理指令与项目记忆；模块自描述由 code-self-describe 负责。
主要能力
- 维护 AGENTS.md：作为跨工具通用指令的编辑点，约束为不超过 60 行、不含特定 AI 工具的专属语法。
- 维护 CLAUDE.md：通过 @AGENTS.md 导入通用信息，并保留 Claude Code 专属补充区；文件已存在时不覆盖补充区。
- 生成编号状态文件：在 docs/devdocs/ 存在的 keel 项目中生成/更新 .claude/rules/devdocs-state.md，编号状态仅写入该文件。
- 信息提取：通用提取来源包括 package.json / go.mod / Cargo.toml（技术栈、运行命令）、README.md（项目概述）、git log（提交约定）、代码结构（关键目录、入口文件）；keel 增强提取来源包括 02-system-design.md（技术栈、架构决策摘要）、01-requirements.md（领域术语）、04-dev-tasks.md（活跃任务与进度）、所有文档（编号状态）。
- 按需参考文档：筛选与精简内容用 best-practices.md；首次创建或重组用 memory-template.md；写 .claude/rules/devdocs-state.md 时用 devdocs-state-template.md（非 keel 项目不加载该模板）。
使用方式
运行模式：
- /agent-memory → 智能检测（AGENTS.md 存在？需要更新？）
- /agent-memory --update → 从项目源提取信息，更新 AGENTS.md
- /agent-memory --restructure → 按最佳实践重组现有 AGENTS.md
各模式的行为：
| 模式 | 读取项目 | 写入文件 | 适用场景 |
|---|---|---|---|
| 智能检测 | 视情况 | 视情况 | 不确定时 |
| --update | 是 | AGENTS.md + CLAUDE.md（若缺失） + devdocs-state.md（仅 keel） | 阶段性工作完成后同步 |
| --restructure | 是 | AGENTS.md + CLAUDE.md | 记忆文件结构混乱时重组 |
智能检测流程：检测 AGENTS.md 是否存在——不存在则扫描项目源，首次创建 AGENTS.md + CLAUDE.md；存在则分析内容状态——信息过时时建议 --update，结构混乱时建议 --restructure。
--update 工作流程：扫描项目信息源（通用提取，以及 docs/devdocs/ 存在时的 keel 增强提取）→ 检查 AGENTS.md 是否存在（不存在则用 memory-template.md 创建，存在则增量更新）→ 提取精华（技术栈、ADR 摘要、领域术语、活跃任务与进度、编号状态（仅 keel）、运行命令）→ 按 best-practices.md 筛选 → 更新 AGENTS.md → 可选 devdocs frontmatter 幂等写入 → 确保 CLAUDE.md 存在 → 生成/更新 .claude/rules/devdocs-state.md → 健康度自检。
--restructure 工作流程：读取现有 AGENTS.md → 按 best-practices.md 检测不规范项（行数限制、工具无关性、章节是否服务当前任务、反模式检测、缺失章节）→ 按 templates/memory-template.md 重组 → 按已授权范围重组并核对差异 → 确保 CLAUDE.md 存在。
适用场景
- 首次创建或全量同步记忆文件。
- 阶段性工作完成后同步 AGENTS.md。
- 记忆文件结构混乱时重组。
限制与边界
- AGENTS.md 不超过 60 行；超限时先压缩带 <!-- agent-memory:managed --> 标记的可再生章节；用户已授权精简或重组时可在指定范围内保留语义地压缩正文，否则需裁剪未受管章节时，展示候选差异并请求确认；无法在保留有效规则的前提下达标时，保留原文件并报告待决项。
- AGENTS.md 不包含特定 AI 工具的专属语法。
- 涉及删除仍有效的用户规则、改变项目决策或无法核实的事实时，先展示具体差异并询问。
- 仅提出建议或只读审查时不写入。
- devdocs-state.md 占位 prose ≤ 200 字符、单行 ≤ 500 字符、文件 ≤ 40 KiB；禁止内嵌 commit hash / LOC / 测试结果 / codex 分数 / 文件路径 / 工时统计。
- devdocs frontmatter 仅在调用方显式传入 devdocs_frontmatter 时写入；未传入时本节步骤全部跳过，行为与现状一致。initialized_at 一旦写入不可修改，传入冲突值时不写入并报告冲突。workspace: 块不受本 skill 管理，一律原样保留。
- 不生成/不修改 00-context.md。
- 静态检查不等于已验证代理行为。
- 健康度自检中，size > 40 KiB 且无 baseline 时阻断，可通过 /pipeline realign --scope=health --apply 或 /agent-memory --update --bypass-state-check="<原因>"（≥10 字符，自动 init baseline）恢复。
Skill 协作
- 首次创建：/agent-memory 自行完成；若 /init 已创建则增量更新。
- 阶段性文档变更：/onboard 完成后建议运行 /agent-memory。
- 任务完成轻量更新：/dev-workflow 内联替换「当前状态」里的任务编号/进度。
- 上下文摘要：/onboard 生成 00-context.md，不涉及记忆文件。
语言与运行
支持中英文提问，统一中文回复。