记忆文件管理

管理 AI Agent 记忆文件（AGENTS.md / CLAUDE.md），支持更新和重构操作。

核心理念

AGENTS.md 为唯一事实源

项目信息源（代码库 + 文档）
    │
    │  提取精华（distill）
    ▼
AGENTS.md（精简、稳定、跨 AI 工具通用）← 通用信息唯一编辑点
    │
    ├── CLAUDE.md（@AGENTS.md 导入 + Claude Code 专属补充）
    ├── .claude/rules/devdocs-state.md（仅 DevDocs 项目，编号状态）
    └── 未来：.cursorrules / .windsurfrules（预留，不实现）

原则：

AGENTS.md 保持工具无关，不包含特定 AI 工具的专属语法
CLAUDE.md 通过 @AGENTS.md 导入通用信息，并可追加 Claude Code 专属补充
工具专属信息通过各自的规则文件补充（如 .claude/rules/）

最佳实践参照

best-practices.md 为所有模式的共享规范：

首次创建时：作为质量基准
--update 更新时：作为内容筛选依据
--restructure 重组时：作为结构验证和反模式检测标准

与 `/init` 的协作

各 AI 工具的 /init 行为不同（如 Claude Code 创建 CLAUDE.md）。本 skill 不假设 /init 产出什么文件，而是保证 AGENTS.md 架构正确：

AGENTS.md 不存在时：自动从项目源扫描并创建
/init 已创建 AGENTS.md 时：后续 --update 在此基础上增量更新
best-practices.md 作为内容质量参考
memory-template.md 作为 AGENTS.md 输出模板

语言规则

支持中英文提问
统一中文回复

运行模式

/agent-memory                    → 智能检测（AGENTS.md 存在？需要更新？）
/agent-memory --update           → 从项目源提取信息，更新 AGENTS.md
/agent-memory --restructure      → 按最佳实践重组现有 AGENTS.md

模式	读取项目	写入文件	适用场景
智能检测	视情况	视情况	不确定时
`--update`	✅	AGENTS.md + CLAUDE.md（若缺失） + devdocs-state.md（仅 DevDocs）	阶段性工作完成后同步
`--restructure`	✅	AGENTS.md + CLAUDE.md	记忆文件结构混乱时重组

智能检测流程

检测 AGENTS.md 是否存在
        │
        ├── 不存在 → 扫描项目源，首次创建 AGENTS.md + CLAUDE.md
        │
        └── 存在 → 分析内容状态
                    ├── 信息过时 → 建议 --update
                    └── 结构混乱 → 建议 --restructure

信息提取分层

通用提取（所有项目）

来源	提取内容
package.json / go.mod / Cargo.toml	技术栈、运行命令
README.md	项目概述
git log	提交约定
代码结构	关键目录、入口文件

DevDocs 增强提取（有 docs/devdocs/ 时）

来源	提取内容
02-system-design.md	技术栈、架构决策 (ADR) 摘要
01-requirements.md	领域术语
04-dev-tasks.md	活跃任务 + 进度
所有文档	编号状态（max F/US/AC/T/ADR）

`--update` 工作流程

1. 扫描项目信息源
   ├── 通用提取（包管理器、README、git、代码结构）
   └── DevDocs 增强提取（若 docs/devdocs/ 存在）
   │
   ▼
1.5 检查 AGENTS.md 是否存在
   ├── 不存在 → 使用 memory-template.md 创建
   └── 存在 → 增量更新
   │
   ▼
2. 提取精华
   ├── 技术栈
   ├── ADR 摘要（若有；无 ADR 格式则从变更记录提取关键决策）
   ├── 领域术语
   ├── 活跃任务 + 进度
   ├── 编号状态（仅 DevDocs 项目）
   └── 运行命令
   │
   ▼
2.5 按 best-practices.md 筛选
   ├── 内容筛选标准：应写入 vs 不应写入
   └── 质量守则：6 条检查
   │
   ▼
3. 更新 AGENTS.md（使用 templates/memory-template.md）
   │
   ▼
4. 确保 CLAUDE.md 存在（若缺失则创建导入文件；已存在则跳过，不覆盖补充区）
   │
   ▼
5. 生成/更新 .claude/rules/devdocs-state.md（仅 DevDocs 项目）

分流规则

信息类型	目标位置	理由
技术栈、运行命令	AGENTS.md	跨工具通用，每次会话都需要
架构决策 (ADR) 摘要	AGENTS.md	防止重复询问
活跃任务 + 进度	AGENTS.md	即时行动上下文
领域术语、业务边界	AGENTS.md	高频稳定，防止误解
代码约定、提交格式	AGENTS.md	跨工具一致
编号状态 (max F/US/AC/T/ADR)	`.claude/rules/devdocs-state.md`	Claude 专属运行态
完整需求/设计/测试详情	留在 `docs/devdocs/`	太详细，不适合记忆文件

`--restructure` 工作流程

1. 读取现有 AGENTS.md
   │
   ▼
2. 按 best-practices.md 检测不规范项
   ├── 行数限制（≤ 60 行）
   ├── 工具无关性
   ├── 章节顺序（对照结构规范）
   ├── 反模式检测
   └── 缺失章节
   │
   ▼
3. 按 templates/memory-template.md 重组
   │
   ▼
4. 展示重组方案，确认后写入
   │
   ▼
5. 确保 CLAUDE.md 存在（若缺失则创建导入文件；已存在则跳过）

输出文件

AGENTS.md

位置：项目根目录
模板：templates/memory-template.md
约束：不超过 60 行，工具无关

CLAUDE.md

位置：项目根目录
结构：@AGENTS.md 导入 + Claude Code 专属补充区
创建时机：AGENTS.md 首次生成时一并创建；已存在则不覆盖
补充区由用户手动维护，/agent-memory 不修改

.claude/rules/devdocs-state.md

位置：.claude/rules/devdocs-state.md
模板：templates/devdocs-state-template.md
条件：仅 DevDocs 项目（docs/devdocs/ 存在时）

约束

内容约束

AGENTS.md 不超过 60 行
AGENTS.md 不包含特定 AI 工具的专属语法
CLAUDE.md 通过 @AGENTS.md 导入通用信息（首次创建后不覆盖）
编号状态仅写入 .claude/rules/devdocs-state.md

质量守则

写入 AGENTS.md 前按 best-practices.md 检查：

6 条守则（短而稳定 / 广泛适用 / 可执行 / 避免重复 / 详情留原地 / 工具无关）
内容筛选标准（应写入 vs 不应写入）
反模式清单

操作约束

不生成/不修改 00-context.md
可删则删，优先命令、约束、检查点
--restructure 重组前必须确认

Skill 协作

场景	协作 Skill	说明
首次创建	`/agent-memory` 自行完成	从项目源扫描创建；若 `/init` 已创建则增量更新
阶段性文档变更	`/devdocs-onboard`	onboard 完成后建议运行 /agent-memory
任务完成轻量更新	`/devdocs-dev-workflow`	dev-workflow 步骤 6.5 内联更新"当前状态"
上下文摘要	`/devdocs-onboard`	onboard 生成 00-context.md，不涉及记忆文件

模板引用

AGENTS.md 模板：templates/memory-template.md
编号状态模板：templates/devdocs-state-template.md
最佳实践：templates/best-practices.md

agent-memory