Project Butler — AI 编程助手的项目记忆系统

你有没有遇到过这样的场景：上周和 AI 助手在项目里埋头苦干了三天，定好了命名规范、架构决策、模块边界，结果周一回来，AI 完全不记得了？你又要重新解释一遍：「这个项目是干啥的，目录结构是这样的，数据库用 PostgreSQL……」这种重复劳动，每次 session 切换都在消耗你的时间和耐心。

Project Butler 解决的就是这个问题。它是一个项目记忆系统，让 Claude Code、Cursor、Codex 这些 AI 编程助手能够跨 session 记住项目的状态、规则、进度和上下文。安装一次，之后每次启动 AI 都能无缝衔接上次的进展，就像一个永不健忘的项目搭档。

背景：AI 编程助手的「健忘症」

2023 年 Claude Code 发布之后，AI 编程助手的上下文窗口可以很长，一个 session 内的表现非常惊艳。但这类工具的设计逻辑决定了：每次新的对话都是一个空白上下文。即使项目已经有几千行代码、完善的 README、详细的 issue 记录，AI 助手也只能靠你在对话里重新描述来获取信息。

GitHub 上有不少解决方案：有人靠粘贴大量上下文，有人靠维护详细的 system prompt，有人靠手工维护项目文档。但这些方法都有一个共同问题：维护成本太高，容易过时，不同工具之间无法共享。

Project Butler 的作者 JamesShi96 正是面对这个痛点，开发了这个工具。它的核心理念来自费曼的名言："如果你不能简单地解释它，你就没有真正理解它。" Butler 的设计目标就是把项目上下文维护得足够简洁、足够结构化，让 AI 助手能够真正理解和记住项目。

核心功能：四个动作覆盖日常使用

Project Butler 提供了四个核心指令，覆盖了日常使用的完整闭环：

• /project-butler — 初始化项目记忆。首次使用时运行，AI 会通过自然对话了解项目基本情况，然后自动生成一套结构化的记忆文件。
• end session — 收工时运行，保存本次工作进度、更新 TODO、整理文件结构，为下一次 session 做好准备。
• continue — 继续上次工作。无需重新解释项目，AI 自动从上次停止的地方继续。
• status — 查看项目现状和下一步建议。

这四个动作构成了一个完整的循环：初始化 → 工作 → 保存 → 继续。不需要理解底层原理，只要会用这四个指令，AI 助手就能成为项目的长期搭档。

底层机制：七层记忆栈

表面上是四个简单指令，背后是 Butler 精心设计的七层记忆栈，按稳定性从高到低组织：

上层（稳定规则）：

• CLAUDE.md（项目宪法）——经过人工审核的项目原则和规范。AI 自动收集候选规则存入 .claude/candidates.md，用户审核后才会成为正式规则。这种机制保证了规则的真实约束力。

中层（当前快照）：

• PROJECT.md（项目 Wiki）——AI 自动同步的当前项目状态，包含概览、结构、模块状态和文件索引。
• STRUCTURE.md（文件组织规则）——定义项目中各类文件应该放在哪里，防止新增文件逐渐散落到随机目录。
• UPDATE_LOG.md（里程碑更新日志）——记录值得保留的项目变化历史，支持 Semantic、Codename、Patch、Date 四种版本命名方式。
• DOCS.md（文档索引）——把项目文档统一归档到 docs/ 目录下。

下层（原始事实）：

• log/（会话日志）——记录每次 session 发生了什么，基于 JSONL 格式存储。
• TODO.md（执行清单）——记录下一步要做什么。

下层喂养上层，上层约束下层。session 日志记录事实，AI 从事实中提炼状态快照，最终沉淀为项目规则。这种自下而上的设计让 Butler 的记忆既不过时（始终来自真实工作），又不过载（规则需要人工确认才生效）。

多工具支持：不是 Claude Code 专属

Project Butler 最初为 Claude Code 设计，但它的输出是纯文件格式的——所有记忆内容都是普通 Markdown 文件。这意味着 Cursor、Codex 或任何能读取项目文件的 AI 助手，都能读取同一套记忆。

为了让非原生工具也能获得更好的体验，Butler 还提供了适配器：

• Cursor：自动生成 .cursor/rules/project-system.mdc，让 Cursor 读取同一套记忆文件。
• Codex：自动生成 AGENTS.md，提供项目指令上下文。
• 其他工具：只要能读取 Markdown，就能使用这套共享记忆。

不过需要明确的是：Claude Code 是原生支持，体验最完整；Cursor 和 Codex 是 best-effort 支持，核心功能可用但不一定完美。

进阶能力：Profile 系统与 Full Context 恢复

对于需要更强产品、架构或调研对齐的项目，Butler 还提供了进阶能力：

Project Profile System：让 Butler 能够根据项目类型（工程项目、调研项目、文档项目等）调整记忆管理的粒度和文档结构。初始化时用户选择项目形态，Butler 会提出相应的 Required / Recommended / Optional 文档结构建议。

Normal Close vs Full Close：

• Normal Close 保存 session 并记录待处理的 Profile 更新（存入 .claude/profile-pending.json）。
• Full Close 则会立即处理 Profile debt，提出 Scope Plan，在确认的边界内安全更新文档。

Continue Full Context：当 session 中断时间较长（比如一周后回来），普通 continue 可能不够用。Full Context 恢复会重建完整的项目轨迹，包括历史会话决策。

语言支持：Butler 支持英文、中文和双语三种模式，可以满足不同团队的需求。

部署与使用门槛

Project Butler 是一个纯 Shell 脚本项目，依赖极少：

• 必须：Claude Code CLI（Anthropic 提供）
• 必须：jq（用于会话恢复时的 JSON 处理）
• 可选：Git（用于自动更新检查）

安装只需一行命令：

git clone https://github.com/JamesShi96/project-butler.git ~/.claude/skills/project-butler

之后在目标项目中运行 /project-butler 即可初始化。安装门槛极低，但对 Claude Code 的依赖决定了它的用户群体主要是 Claude Code 重度用户。

局限与争议

依赖 Claude Code CLI：这是最大的门槛。如果你不使用 Claude Code，Butler 的价值大打折扣。虽然支持文件式接入其他工具，但原生体验差距明显。

规则膨胀风险：随着项目推进，CLAUDE.md 可能积累大量规则。过多规则会导致 AI 难以全部遵守，这需要用户定期清理。

项目类型限制：Butler 的文档结构和 Profile 系统更适合软件工程类项目。对于纯研究代码、数据分析项目，维护一套完整记忆文件的成本可能高于收益。

会话日志长期存储：JSONL 日志会随时间增长，如果项目周期很长，日志文件可能变得庞大，需要定期 compaction。

总结与行业意义

Project Butler 代表了一个新兴的细分方向：AI 编程助手的上下文工程（Context Engineering）。2025-2026 年，随着 Claude Code、Cursor、Codex 等工具的普及，如何维护高质量的项目上下文成为一个越来越受关注的话题。

从增长数据看，这个项目在 2026 年 4 月创建，到 7 月已有 265 star，月趋势得分高达 86.99，说明这个方向正处于上升期。但它相对小众——主要用户是 AI 编程助手的高级用户，而非普通开发者。

适合使用 Project Butler 的场景：

• 长期维护的软件项目，需要 AI 持续理解项目上下文
• 同时使用多个 AI 编程工具，需要统一的上下文来源
• 中大型项目，有明确的架构规范需要 AI 遵守
• 团队协作场景，需要 AI 理解项目规则

不太适合的场景：

• 一次性脚本或短期项目
• 纯研究代码或数据处理
• 不使用 Claude Code 的用户

如果你每天都在和 AI 编程助手打交道，同时又在多个项目中切换，Project Butler 值得一试——它让 AI 真正成为了解你项目的长期搭档，而不是每次都要重新认识的陌生人。