Project Butler 项目管家

这个 Agent 能做什么，适合哪些场景？

project-butler 是一个面向 AI 编程助手的项目记忆系统，以 Claude Code 技能的形式安装在 ~/.claude/skills/project-butler 下。它通过在项目根目录维护一组纯 Markdown 文件（CLAUDE.md、PROJECT.md、STRUCTURE.md、UPDATE_LOG.md、DOCS.md、session-handoff.md、TODO.md，以及 log/、docs/、.claude/ 目录）来记录规则、当前状态、待办、里程碑变更和会话日志。用户在会话结束时说“end session”保存进度，下次说“continue”即可恢复上下文，无需重新解释项目。内部按 7 个组件组织记忆栈：稳定规则、当前状态与原始事实自下而上汇总，top 约束 bottom。v1.6.0 起引入 Project Profile System，通过 .claude/project-profile.json 与 .claude/profile-pending.json 追踪文档分层、待办配置更新与 Normal Close / Full Close 行为。原生运行依赖 Claude Code 技能生命周期与 jq，Cursor 与 Codex 只能通过生成的规则文件进行尽力而为（best-effort）适配。

运行 /project-butler 时，技能在项目根目录创建或补齐 CLAUDE.md、PROJECT.md、STRUCTURE.md、UPDATE_LOG.md、DOCS.md、session-handoff.md、TODO.md，以及 docs/、log/、.claude/ 目录和 .claude/project-profile.json、.claude/profile-pending.json、.claude/candidates.md、.claude/.file-snapshot.json。工作过程中它把会话事实写入 log/，把待执行事项写入 TODO.md，把候选规则写入 .claude/candidates.md 等待用户通过 review claude 审核后才升格为长期规则。end session 会总结进展、刷新下一步、按用户选择的版本风格（Semantic / Codename / Patch / Date）写入 UPDATE_LOG.md。continue 与 continue full context 通过 jq 解析日志恢复上下文与完整项目轨迹。organize files 依据 STRUCTURE.md 执行四阶段（Discover、Ask or Plan、Plan、Execute）文件整理并遵守不删除策略。每次调用时技能还会对自身仓库执行 git fetch 并与 origin/main 比较 HEAD，判断是否落后并提示更新（可用 PROJECT_BUTLER_NO_UPDATE_CHECK=1 关闭）。

1. 长期用 Claude Code 迭代同一个代码库、每次会话都要重新讲一遍架构的开发者。
2. 在 Claude Code、Cursor、Codex 之间切换、希望三种工具读到同一份项目记忆的用户。
3. 需要把架构决策、命名约定沉淀为可审核长期规则、而不是留在聊天记录里的团队。
4. 项目文档散落在多个文件夹、希望按 STRUCTURE.md 自动整理并建立 DOCS.md 索引的维护者。
5. 经常中断数周再回来、需要 continue full context 重建项目全貌的个人开发者。
6. 需要区分 Normal Close 与 Full Close、对产品/架构/路线图文档做受控更新的产品型项目。

如何安装或部署这个 Agent？

以 Claude Code 技能方式克隆到技能目录：

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

前置条件：需要 Claude Code CLI（原生技能执行）、jq（用于 continue / continue full context 会话恢复）。若在 v1.7.0 之前安装，需手动拉取一次以启用自动更新检查：

cd ~/.claude/skills/project-butler && git pull

如需关闭自动更新检查：

export PROJECT_BUTLER_NO_UPDATE_CHECK=1

非 Claude Code 环境下手动检查更新：

bash "${PROJECT_BUTLER_SKILL_DIR:-$HOME/.claude/skills/project-butler}/scripts/check-update.sh"

没有独立的 /continue 命令需要安装，会话恢复由主技能内部路由。

如何使用这个 Agent？

打开任意项目后首次初始化：

/project-butler

日常四个动作即可覆盖主要流程：

end session     # 保存进度与下一步
continue        # 下次直接接续上下文
status          # 查看项目当前状态与建议的下一步

高级用法：

continue full context      # 长时间中断或换助手后重建完整轨迹
review claude              # 审核候选规则
sync wiki                  # 强制刷新 PROJECT.md
organize files             # 按 STRUCTURE.md 整理新文件
change language            # 切换英文 / 中文 / 双语模式
normal close               # 保存会话并把影响 profile 的更新推入待处理队列
full close                 # 在受限 Scope Plan 内立即对齐相关 profile 文档
profile setup              # 创建或修复项目 profile 与基线参考文档

这个 Agent 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

与相关度最高的同类 agent 并排比较关键指标。

FollowAgents 如何评估这个 Agent？

最近版本

来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。

1. v1.7.3 v1.7.3 — Interactive Update Prompt + Project Profile System 2026-07-29
   发布说明摘录

   First release since v1.4.0. It rolls up everything from v1.4.1 through v1.7.3 — two big additions (Project Profile System, version freshness check), a versioned update log, and a round of test-driven hardening. Highlights 🔔 Version freshness check (v1.7.0 → v1.7.3) project-butler now tells you when your installed copy is behind upstream. Every invocation starts with a cached check (at most one git fetch per machine per day) comparing local HEAD to origin/main. When you're behind, Claude Code asks once — and at most once every 24 hours: ``` …

   在 GitHub 查看 ↗
2. v1.4.0 v1.4.0 — Document Archiving System 2026-06-01
   发布说明摘录

   Document Archiving System Add a document archiving layer to the project memory stack. New files: - docs/ directory — organized document storage with 6 preset type subdirectories - DOCS.md — document index with metadata (title, status, last updated, sub-doc hierarchy) - references/document-archiving.md — archiving protocol with auto-classification rules 6 preset document types (selected during init, extensible): - PRD, Tech Design, Design Docs, Research, Meeting Notes, Experiments End session integration: …

   在 GitHub 查看 ↗
3. v1.3.0 v1.3.0 — Four-Phase File Reorganization 2026-06-01
   发布说明摘录

   Four-Phase File Reorganization Replaced template-based file reorganization with a project-understanding-driven flow. Mode A redesign (整理文件): - Four-phase flow: Discover → Ask or Plan → Plan → Execute - Phase 1 (Discover): structural signals first (glob/grep/imports), content reading only for uncertain files, then relationship inference to build a module map - Phase 2 (Ask or Plan): three-tier confidence routing — high confidence skips straight to plan, medium confidence (most common) focuses on specific issues, low confidence asks user about organizing dimensions …

   在 GitHub 查看 ↗

常见问题