SUNQSHENG/project-registry

¿Qué hace project-registry?

EN — A Claude Code skill that manages a personal project registry (~/projects/PROJECTS.json) with per-project AI-readable development logs (CLAUDE.md): list, create, delete, save, session-resume, decision attribution, health check and version rollback from one menu. The UI text is Chinese-first, but triggers work in both Chinese and English and every feature is fully functional regardless of language (the AI understands both). Install: npx skills add SUNQSHENG/project-registry or /plugin marketplace add SUNQSHENG/project-registry.

概述

管理 ~/projects/PROJECTS.json 注册的项目清单，提供项目的增删改查和统计功能。项目以 <key>/ 子目录形式存放在 ~/projects/ 下，每个项目包含 README.md 记录背景和范围。

操作项目时自动 cd 到对应项目目录。

数据源

~/projects/
  PROJECTS.json    # 项目注册清单（唯一权威来源）
  <key>/           # 项目目录
    README.md      # 项目背景和范围说明（面向人）
    CLAUDE.md      # 项目开发记录（面向 AI，每次对话自动加载）

所有项目必须存放在 ~/projects/ 目录下。

区别： README.md 给开发者/协作者看项目概况；CLAUDE.md 给 AI 看，记录开发过程中的决策、状态、上下文，确保长项目不丢失信息。

PROJECTS.json 结构

{
  "description": "项目清单 — 所有项目在此登记",
  "updated": "2026-03-01",
  "nextSeq": 3,
  "projects": [
    {
      "seq": 1,
      "key": "pet_hospital_crm_20260301",
      "name": "宠物医院CRM",
      "status": "已完成",
      "created": "2026-03-01"
    }
  ]
}

操作入口

每次进入 skill 时，先 cd ~ 回到用户根目录，然后读取 PROJECTS.json 展示清单和精简菜单（不做目录级检测）：

📋 当前项目清单（共 N 个）
┌─────┬──────────────────────────────┬─────────────────┬──────────────────────┬──────────┬────────────┐
│ 序号 │ key                          │ 名称             │ 状态                 │ 创建日期   │
├─────┼──────────────────────────────┼─────────────────┼──────────────────────┼──────────┼────────────┤
│ 1   │ pet_hospital_crm_20260301    │ 宠物医院CRM      │ ✅ 已完成            │ 2026-03-01 │
│ 2   │ gym_members_app_20260315     │ 健身房会员App    │ 🔄 进行中            │ 2026-03-15 │
└─────┴──────────────────────────────┴─────────────────┴──────────────────────┴──────────┴────────────┘

> 初始展示不做目录检测，仅读 JSON。目录状态在 MD检查 时批量检测。

请选择操作（或直接说需求）：
 - 输入项目**序号**（1-99）→ 打开对应项目（如 12）
 - 🆕 N. 新建项目
 - 🗑️ D. 删除项目
 - 🔍 C. MD检查（批量检测所有项目）

> 其他需求（修改/搜索/统计/更新记录/保存/退出/**检查项目**/**为什么 XX**）直接在对话中说即可
> ⚠️ **保存/退出时会自动更新 CLAUDE.md**（强制规则）

⚙️ 首次配置引导（API Key 可选）

第一次进入 skill 时：

1. 检查环境变量 PR_API_BASE_URL / PR_API_KEY / PR_API_MODEL 是否配置（printenv）
2. 未配置 → AskUserQuestion 卡片询问：「是否配置 API Key 启用自动摘要保存？」
   • 配置（推荐） → 引导设置三个环境变量（README 有各提供商示例：DeepSeek / OpenAI / 通义 / Ollama 本地）
   • 跳过 → 写入 <skill 目录>/config.json（记"已跳过"，后续不再问）
   • 了解更多 → 展示功能对比表
3. 配置后立即生效（无需重启会话）

功能对比：

能力	不配 Key	配 Key
数据安全（秒级备份 + 会话结束自动提交）	✅	✅
全部核心功能（注册表/会话恢复/归因/回滚/检查）	✅	✅
自动摘要（对话自动提炼 → CLAUDE.md 实时更新）	❌	✅

随时说「配置 API」可重新引导。

🔍 自动识别当前项目

每次进入 skill 时已自动 cd ~。需要定位项目的操作（检测/修改/保存/更新记录等）自动识别当前目录：

1. pwd 检查是否匹配 ~/projects/<key>/
2. 匹配 → 自动选定该项目
3. 不匹配 → 手动选择（按序号或 key）

🧭 会话开始流程（上下文恢复）

仅对「进入项目工作」类操作触发：打开项目 / 检测 / 修改 / 更新记录 / 保存 / 退出。查看详情、搜索、统计等轻操作不触发。

进入项目后、执行操作前，先回顾上下文再续接（防止长项目信息丢失、中断后重新进入不知从何下手）：

1. 读取该项目的 CLAUDE.md（若存在）
2. 摘要上次进展：引用「当前状态 / 最新进展」，必要时结合 git log 最近提交
3. 列出「下一步行动」（按优先级 1. 2. 3. …）
4. 询问用户从哪项继续（用 AskUserQuestion 卡片呈现下一步行动选项），确认后再操作

示例话术（卡片下方附注）：

📌 上次进展摘要：项目初始化完成，注册表已建
➡️ 下一步行动（按优先级）：
  1. 完成需求文档
  2. 补充待办列表
从哪项继续？

新项目（CLAUDE.md 刚创建）可跳过回顾，直接进入操作。

📂 打开项目

1. 按序号或 key 定位项目 → 校验 ~/projects/<key>/ 目录存在
2. cd 到项目目录
3. 触发「🧭 会话开始流程」（回顾上次进展 → 确认续接）
4. 用户在项目内开始工作后，按需操作（修改/更新记录/保存/退出）

操作详情

📌 交互规则（强制）：所有需要用户「是/否」或「多选一」的询问，必须使用 AskUserQuestion 工具以选项卡片呈现（两个及以上选项按钮），禁止用纯文本提问。适用场景：是否引入 grill-with-docs、是否建立文档骨架、项目类型确认、key/背景确认（按建议 or 修改）、删除确认、会话续接选择（从哪项继续）等。

🆕 新建项目

1. 询问项目名称 + 背景说明，生成 key：<英文缩写>_<YYYYMMDD>
2. 备份 PROJECTS.json → 创建目录 → 写入 README.md + CLAUDE.md + .gitignore（含 PROJECTS.json、backups/、*.bak、.memory/）
3. 注册到 PROJECTS.json（seq = nextSeq, 之后 nextSeq +1）
4. cd 到项目目录，git init
5. 必须询问是否引入 grill-with-docs skill（AskUserQuestion 卡片：引入 / 不引入）：
   • 同意 → 落实三个动作（不是口头"已引入"）： ① CLAUDE.md「依赖关系」表记录：| grill-with-docs | 引入 | 设计拷问流程（需用户手动调用 /grill-with-docs）| ② 初始待办顶部加一条提醒（标注「手动」，非可执行任务）： - [ ] 📌 提醒（手动）：设计/规划时输入 /grill-with-docs 启动拷问（该 skill 仅限用户手动调用，AI 无法代激活） ③ 明确告知用户调用方式：「首次设计/规划时手动输入 /grill-with-docs」
   • 拒绝 → 不记录、不加入待办，正常继续
6. 代码/工程类项目：询问是否建立可选文档骨架（AskUserQuestion 卡片：建立 / 跳过；见「📁 可选文档骨架」）；业务/文档类项目跳过

CLAUDE.md 初始模板见底部。

🗑️ 删除项目

1. 定位项目 → 列出 JSON 条目 + 目录文件清单 → 标注不可逆风险
2. 用户确认后：备份 PROJECTS.json → 删除 JSON 条目 → 删除项目目录 → 剩余项目从 1 连续重编号 → nextSeq = max(seq) + 1

💾 保存项目

1. 备份 CLAUDE.md（到 <skill 目录>/backups/，即 ~/.claude/skills/project-registry/backups/）
2. 回顾本次对话，将以下内容追加或更新到 CLAUDE.md：
   • 最新进展和完成事项
   • 新增的架构决策（日常决策按「📜 决策记录纪律」格式补录，原因不可省略）
   • 更新待办列表（已完成项标记 ✅，新增项添加）
   • 更新已知问题
   • ⚠️ 「下一步行动」必须按优先级列出（1. 2. 3.），不可省略（下次会话从这里续接）
3. 提交 CLAUDE.md 变更到 git
4. 建议下一步工具：根据项目内容和待办，提示可能用到的 skill（如 ppt-master / docx / xlsx / pdf 等），供用户决定
5. 保存后不退出，留在当前目录

⚠️ CLAUDE.md 自动更新是强制规则，不可跳过。

🚪 退出项目

同保存操作，但最后一步退回 ~：

1. 备份 CLAUDE.md
2. 回顾本次对话更新 CLAUDE.md（含「下一步行动」按优先级）
3. 提交 变更到 git
4. 建议下一步工具（同保存流程）
5. 退出后直接退回 ~

🔍 MD检查（批量检测所有项目 CLAUDE.md 状态）

对所有已注册项目批量检查 CLAUDE.md 是否有效（无需手动选择）：

1. 遍历所有项目目录，检查以下 3 项：
   • 目录是否存在
   • CLAUDE.md 是否存在
   • .git 是否存在（CLAUDE.md 生效前提：必须与 .git 同级）
2. 输出汇总表格：

🔍 MD 健康检查（共 N 个项目）
┌─────┬─────────────────────────────┬─────────────────┬──────────┬──────────┬──────────┬──────────┐
│ 序号 │ key                         │ 项目名称         │ 目录存在  │ CLAUDE.md│ .git     │ 有效?   │
├─────┼─────────────────────────────┼─────────────────┼──────────┼──────────┼──────────┼──────────┤
│ 1   │ pet_hospital_crm_20260301   │ 宠物医院CRM      │ ✅       │ ✅       │ ✅       │ ✅      │
│ 2   │ gym_members_app_20260315    │ 健身房会员App    │ ✅       │ ✅       │ ✅       │ ✅      │
│ ... │ ...                         │ ...              │ ...      │ ...      │ ...      │ ...      │
└─────┴─────────────────────────────┴─────────────────┴──────────┴──────────┴──────────┴──────────┘

3. 对「有效?」为 ❌ 的项目，逐个定位问题：
   • 目录不存在 → 检查 JSON 注册是否有残留
   • CLAUDE.md 缺失 → 用模板补创建
   • .git 缺失 → 执行 git init
4. 自动 cd 到用户根目录（不进入具体项目）

📁 可选文档骨架（代码/工程类项目）

新建代码类项目时询问是否建立（业务/文档类项目跳过）。建立后与 CLAUDE.md 分工：CLAUDE.md 记录状态和决策，骨架文档记录设计细节：

<项目目录>/
├── CLAUDE.md              # 开发记录（状态/决策/待办）
└── docs/
    ├── ARCHITECTURE.md    # 整体架构说明（可选）
    ├── adr/               # 架构决策记录（可选，与 grill-with-docs/domain-modeling 的 ADR 输出衔接）
    └── dev/
        ├── README.md      # 功能索引
        └── <feature>/
            ├── SPEC.md    # 功能规格
            └── DESIGN.md  # 实现设计

轻量原则：仅在用户确认时创建，不强制、不默认。 与 grill-with-docs 衔接：grill-with-docs（拷问+术语+ADR）是设计流程，骨架是落盘结构——先拷问清楚，再按骨架存储。分工：轻决策记入 CLAUDE.md「架构决策记录」（一行式）；难逆转、有真实权衡的决策落 docs/adr/；术语表 CONTEXT.md 由 domain-modeling 专属维护，骨架不重复建。

自动 cd + CLAUDE.md 自动更新

操作	cd	CLAUDE.md 自动更新
新建	进入项目目录	✅ 自动创建初始模板
检测/修改	进入项目目录	❌ 不自动更新
更新记录	进入项目目录	✅ 手动触发更新
保存	进入项目目录，保存后不退出，留在目录	✅ 自动更新
退出/返回	先更新 CLAUDE.md，再退回 ~	✅ 自动更新

安全机制

PROJECTS.json 写操作（新建、修改、删除）必须先备份：

备份路径：<skill 目录>/backups/（即 ~/.claude/skills/<skill-name>/backups/）
备份文件：PROJECTS.json.<YYYYMMDD_HHMMSS>.bak

CLAUDE.md 写操作（更新记录、保存时自动更新）必须先备份：

备份路径：<skill 目录>/backups/
备份文件：CLAUDE.md.<YYYYMMDD_HHMMSS>.bak

如果备份目录不存在，自动创建。

备份自动轮转：

每次新建备份后，按文件类型清理旧备份，每种类型保留最近 10 份：

备份类型前缀：
  PROJECTS.json.*.bak    # 项目清单备份，保留 10 份
  CLAUDE.md.*.bak        # 开发记录备份，保留 10 份
  SKILL.md.*.bak         # 本 skill 自身备份，保留 10 份

清理规则：按文件名末尾的 YYYYMMDD_HHMMSS 提取时间戳排序（注意：CLAUDE.md.<项目名>.<时间戳>.bak 这类特殊命名的备份，时间戳在末尾，不能用整名字符串排序），保留最晚的 10 份，其余删除。

🔁 自动保存（hooks，静默执行）

两层机制，全部后台静默、失败静默重试、只在 ~/projects/ 项目目录生效。

层 1 机械快照（零依赖，默认开启）

Hook	动作
Stop（每次响应后）	transcript 同步到 <项目>/.memory/transcript-latest.jsonl（秒级）
SessionEnd（会话结束）	CLAUDE.md 备份（10 份轮转）+ git 提交（有变更才提交）

• ⚠️ 隐私：.memory/ 含对话原文——必须 gitignore 排除（新建项目自动生成 .gitignore 含 .memory/），绝不进仓库
• 强杀终端时 SessionEnd 不触发，但 Stop 的秒级同步仍在——数据不丢

层 3 自动摘要（可选，配置 API 后启用）

• 触发：节流控制（≥10 条新消息 或 ≥10 分钟）——不每次响应都调 API
• 流程：读 .memory/ 增量 → 调用 PR_API_BASE_URL（任意 OpenAI 兼容提供商）→ 提取进展/决策/待办/下一步 → 合并更新 CLAUDE.md（追加决策/更新进展/待办/下一步）
• 配置（环境变量）：PR_API_BASE_URL / PR_API_KEY / PR_API_MODEL（不配置自动跳过）
• 隐私：对话只发送到用户自己配置的端点；key 从环境变量读，永不硬编码

与手动保存的关系

自动摘要 = 实时保鲜（增量合并）；手动保存 = 权威整理（全面回顾）——两者兼容互补。

📜 决策记录纪律（查必有据）

所有决策必须可回溯：「为什么这么做」永远可查，原因不可省略。

轻决策格式

- [状态] YYYY-MM-DD — <决策>（原因：<理由>）（预期：<效果>）

• 状态标记：✅已执行 / 🔄进行中 / ⛔被推翻 / ⏸️搁置
• 原因强制：无原因不上记录
• 预期可选：记录时已知预期效果则补上（归因时用于验证效果）

记录时机（分层）

类型	时机
重大决策（影响方向 / 难逆转 / 消耗资源）	对话中即时确认：Claude 主动询问「这条记入决策记录吗？」
日常决策	保存/退出时统一回顾补录（强制）

重决策 → ADR

难逆转、有真实权衡的决策落 docs/adr/，CLAUDE.md 留一行索引：

- 2026-08-08 — ADR-0001 <决策标题>（状态：✅已执行）

ADR 结构：# ADR-000N <标题> + Status / Date / Context / Decision / Consequences。

CLAUDE.md 初始模板

# <项目名称>

## 项目目标
<背景说明摘要>

## 技术栈
（待补充 — 语言/框架/数据库/部署等）

## 当前状态
state: active
- 阶段：需求分析 / 开发中 / 已完成
- 最新进展：项目初始化

## 架构决策记录
记录所有重要决策，格式：
- [状态] YYYY-MM-DD — <决策>（原因：<理由>）（预期：<效果>）
（状态：✅已执行 / 🔄进行中 / ⛔被推翻 / ⏸️搁置；原因不可省略，预期可选）

## 项目范围与功能
（核心功能清单，也可用表格呈现）

## 依赖关系
| 依赖项目 | 关系 | 说明 |
|:---|:---|:---|
| <项目名> | 依赖/被依赖 | <具体说明> |

## 待办
- [ ] 待办事项 1（细化到可执行的粒度）

## 已知问题
- （暂无 — 发现后补充，含影响范围）

## 下一步行动
- 按优先级列出（1. 2. 3.），保存/退出时强制更新

新建时至少填充：项目目标、技术栈、当前状态、待办前三项。其余在开发过程中逐步丰富。

key 命名规则

<英文/拼音缩写>_<YYYYMMDD>

示例:
  宠物医院CRM      → pet_hospital_crm_20260301
  健身房会员App    → gym_members_app_20260315

• 英文优先，拼音备选
• 全小写，下划线分隔
• 尾部加日期

序号管理规则

操作	规则
新建	读取 nextSeq 作为新项目的 seq，注册后 nextSeq +1
删除	删除后剩余项目从 1 开始连续重新编号，nextSeq 设为 max(seq) + 1
seq	始终连续，永不跳号

🧠 记忆管理（三层机制）

项目级记忆（skill 管理）

记忆载体	记什么	管理机制
CLAUDE.md	状态 / 决策及原因 / 待办 / 已知问题 / 下一步行动	每次会话自动加载 + 保存强制更新 + git 提交 + 备份轮转
PROJECTS.json	项目注册清单（seq/key/name/status/created）	写操作前备份
git 历史 + backups/	历史版本快照	任意时刻可回溯（git show / 备份文件）

记忆生命周期

写入（保存/退出强制更新）
  → 自动加载（每次会话 Claude Code 自动注入 CLAUDE.md）
  → 备份（10 份轮转 + git 提交）
  → 检索（读 CLAUDE.md / 归因调查「为什么 X」/ git 历史回溯）

记忆边界

记录：架构决策及原因 | 约定和规范 | 领域术语 | 待办和已知问题 | 当前状态和依赖 | 下一步行动

不记录：详细代码实现 | git 可回溯的变更 | 临时性讨论（对话原文不存档——查"当时具体聊了什么"用 Claude Code 自带会话存档 --resume，不在本 skill 职责内）

与全局记忆的分工

• 项目相关（进展/决策/为什么这么定）→ 本 skill 记忆（CLAUDE.md，跟着项目走）
• 用户偏好/跨项目事实（如"PPT 优先用 ppt-master"）→ Claude Code 全局记忆（~/.claude/.../memory/，由系统维护，skill 不写）

CLAUDE.md 维护

CLAUDE.md 是 Claude 每次对话自动加载的项目上下文文件，记录决策和进展。

更新时机（强制规则）： 新建时自动生成 | 每次对话结束调用"更新记录" | 关键决策时追加 | 需求变更时同步 | ⚠️ 退出或保存时自动执行更新（必须执行，不可跳过），且「下一步行动」按优先级写出

记录什么： 架构决策及原因 | 约定和规范 | 领域术语 | 待办和已知问题 | 当前状态和依赖 | 下一步行动

不记录： 详细代码实现 | git 可回溯的变更 | 临时性讨论

生效条件： 必须和 .git 同级，文件名 CLAUDE.md（全大写）

新建项目时自动 git init。已有目录无 .git 时，告知原因并询问是否要 git init。

🔎 归因调查（为什么 X）

用户说「为什么 X / 这个决策的背景 / 当时为什么这么做 / 归因 X」时触发。

流程：

1. 定位：确认调查对象（项目 + 主题/时间点）
2. 取证：读取该项目 CLAUDE.md「架构决策记录」+ docs/adr/（若存在）+ git log 最近提交 + 进展/待办
3. 输出归因报告：
   • 决策时间线：相关决策按时间排列
   • 原因链：每个决策的理由 + 决策间关联（哪个决策基于哪个）
   • 状态：✅已执行 / 🔄进行中 / ⛔被推翻 / ⏸️搁置
   • 后续影响：结合最新进展判断预期是否达成
4. 结论：回答「当时为什么这么做」，必要时指出预期是否被验证

输出在对话内；要求存档时落盘到仓库外（~/project-audit-logs/）——检查/归因内容含项目隐私，禁止写入项目仓库。

📋 项目检查（自然语言触发，不占菜单）

用户说「检查项目 / 体检 / audit」时触发，菜单不新增项。

全部扫描（「检查所有项目」）

结构检查（同 MD检查 C）+ 内容 5 项：

#	维度	检查逻辑
1	状态一致性	PROJECTS.json 的 status vs CLAUDE.md 最新进展/待办是否矛盾
2	项目停滞	CLAUDE.md 最近更新（git log 时间）距今 > 14 天 → 「可能停滞」
3	待办堆积	未完成待办超 10 项 或 长期无进展
4	决策未落地	决策记录标 ✅已执行 但进展/待办无体现
5	下一步缺失	无「下一步行动」章节（保存流程偷懒）

异常项自动带归因线索：回溯最近 N 条决策，指出哪些决策可能相关。

单项目深查（「检查 XX 项目」）

内容 5 项，只查指定项目。

报告只在对话内输出；要求落盘时存到 ~/project-audit-logs/（仓库外）。

↩️ 版本回滚

用户说「回滚 / 恢复版本 / 退回 / 撤销保存」时触发。双通道：git 历史（项目文件）+ 备份快照（注册表/开发记录）。

通用安全规则（所有回滚必须遵守）：

1. 先备份当前版本（回滚本身可回滚）
2. 必须展示差异摘要 + AskUserQuestion 卡片确认（回滚 / 取消）后才动手
3. 回滚产生新提交，不改写 git 历史

① CLAUDE.md 回滚（开发记录误改/误删）

1. 定位：git log --oneline 列出最近提交（或 backups/CLAUDE.md.*.bak 文件名时间戳）
2. 对比：git show <commit>:CLAUDE.md 与当前版本的差异（重点：决策/待办/下一步行动）
3. 确认：展示差异摘要 → 卡片确认
4. 执行：备份当前版 → git checkout <commit> -- CLAUDE.md → 提交（记录"回滚到 "）
5. 汇报：回滚内容摘要

② 项目文件回滚（README/docs/代码）

1. 定位：git log 找目标版本
2. 对比：git diff <commit> -- <文件>
3. 确认：差异摘要 → 卡片确认
4. 执行：备份当前版 → git checkout <commit> -- <文件> → 提交
5. 汇报

③ 注册表回滚（PROJECTS.json 误删/误改）

1. 定位：backups/PROJECTS.json.<时间戳>.bak（最近 10 份，按末尾时间戳排序）
2. 对比：当前 vs 备份 diff（列出项目增减）
3. 确认：差异摘要 → 卡片确认
4. 执行：备份当前版 → cp 备份 → PROJECTS.json → 校验（项目数/seq 连续性）
5. 汇报

提示：回滚与「🔎 归因调查」配合——先查"为什么变成这样"，再决定回滚到哪个版本。

常见问题

• PROJECTS.json 不存在：用默认模板创建空清单
• 目录已存在：复用现有目录，仅注册 JSON
• 删除时找不到项目：先列出清单让用户确认