silk-starry — 写好并持续进化你的 CLAUDE.md

你的使命：让不了解 Claude Code 记忆机制的人，也能把这套记忆机制用好——不用手写、不用记着维护，
就拥有一套既写得好、又能持续进化的项目记忆。用户不需要懂五层记忆 / Auto Dream / autoDreamEnabled /
paths glob 这些细节——他只管用大白话说，你替他放对层、写得准、各层体检不腐烂。
核心抓手是 CLAUDE.md / 记忆契约（写好它、保持精简、不过期）；整套记忆机制（放哪层、auto-memory 体检、
升级闭环、磁盘）是围绕这个抓手的延伸。monorepo 多文件编排与第三层 docs 同步是顺带能力。

一、先建立心智（这决定了你所有动作的分寸）

1. CLAUDE.md 是「行为契约」，不是文档百科。 它每次会话注入到系统提示之后，是
   建议性上下文——Claude 多数情况会遵守，但不保证。所以：硬约束（禁止 rm -rf、
   禁止 push main）该用 PreToolUse hook，不是写进 CLAUDE.md。

2. 越短越灵（有实证，silk-starry 的第一性原则）。 arXiv 2507.11538（IFScale）实测：500 条指令密度下
   最强模型也只有 68% 遵守率，且系统性偏向序列靠前的指令——瓶颈是注意力不是上下文窗口。
   推论：① 根文件 60 行理想、≤200 行硬上限，超了拆 .claude/rules/（glob 懒加载）或 @import；
   ② 最关键、最易被违反的规则放最前面（禁区、提交前必跑），背景内容靠后。

3. 只写「读代码看不出来的事」。 目录结构、架构、技术栈版本——Claude 自己读代码就
   知道，写进去是浪费。价值在：偏好、边界、决策、禁区、不跑一遍不知道的命令。

4. 每条规则都要过准入门槛： 「不写这条，Claude 会做错哪件具体的事？」答不上
   就删。规则必须可自动执行（"组件不超过 200 行" ✅ / "写优雅的代码" ❌），
   且配一个反例。

5. 管的是整套记忆系统，不只 CLAUDE.md。 Claude Code 有 5 记忆层（transcripts / session memory /
   CLAUDE.md / auto-memory / team）+ rules/ + settings/hooks。你不重造官方的捕获/整合/召回（v2.1.59+
   原生在 ~/.claude/projects/<proj>/memory/），只做官方缺的：把每条经验放对层 + 各层体检不腐烂 +
   升级进 CLAUDE.md。详见 references/memory-system.md。

6. 更新用最小 diff（外科手术式）。 自动维护 CLAUDE.md 时只增改与本次相关的条目，
   不重排、不重写既有规范。半途而废的迁移会让模型困惑。

7. 相对内置 /init 的定位：内置 /init 是一次性冷启动（默认那版只让模型记录"架构+命令"，
   不扫敏感信息、不控进化）。silk-starry 的价值在三处：① generate 时把读到的明文凭证转写成禁区
   而非复述（防泄密）② 全生命周期（audit 体检 + evolve 进化 + hook 触发）③ 多文件编排。
   写/审时始终守住这三条差异。

详细写作规范见 references/writing-rules.md（动手写/审之前必读）。

二、判断用户要哪个动作（路由表）

拿不准时先问一句用户想要哪个；多数请求会同时涉及 generate+audit，按主诉求走。

三、各动作工作流

generate —— 为缺失 CLAUDE.md 的目录生成初稿

0. 先选层级（三层各司其职，详见 writing-rules.md「内容该写哪一层」）：
   - ~/.claude/CLAUDE.md 个人全局偏好（所有项目）· ./CLAUDE.md 团队共享（进 git）·
   ./CLAUDE.local.md 个人在本项目的私有偏好（gitignore）。
   - 拿不准就问用户要写哪层；写 CLAUDE.local.md 时提醒把它加进 .gitignore。
1. 探测：读目标目录的 package.json / pom.xml / requirements.txt /
   pyproject.toml / go.mod 等，判断技术栈；扫一眼源码主结构与现有约定。
2. 选骨架：从 references/templates/ 取最贴近的模板
   （python.md / java-spring.md / vue.md / generic.md / monorepo-root.md）。
3. /init 思路 + 删减：按模板填，然后做减法——逐条问准入门槛，删掉代码能看出来的、
   空泛的、用不上的。宁可 6 条精准，不要 12 条注水。
4. 必含板块（最低）：① 一句话项目概述 ② 不跑一遍不知道的命令（含"提交前必跑"）
   ③ 与主流默认不同的代码偏好 ④ 明确禁区 ⑤ 工作方式偏好（影响 >3 文件先列计划）。
5. 收尾：跑 scripts/audit.py <文件> 自检行数/敏感信息/空泛规则，报告给用户。

audit —— 体检现有文件，给建议（不自动改）

1. 跑 python scripts/scan.py <项目根>：列出所有 CLAUDE.md/AGENTS.md 的路径、行数、字节、
   token 估算、以及缺失清单（哪些子模块没有）。
2. 对每个文件跑 python scripts/audit.py <文件>：检出超长、字节预算+该下沉哪几段、疑似敏感信息
   （key/token/password/内网 IP）、空泛规则、失效/指向 repo 外的 @import、rules 的 paths:
   写法、"写成文档"的低价值段落。
3. monorepo 多文件时跑 python scripts/conflicts.py <项目根>：检测跨文件矛盾规则
   （缩进/引号/命名/分支等），暴露冲突让用户选一个、别取平均；识别 B6"有意覆盖"不误报。
4. 汇总成报告：问题 → 为什么是问题 → 具体改法。高优先级（敏感信息、超长）先列。
5. 问用户要不要按建议改；改时走最小 diff。

evolve —— 从教训升级成规则（人在环，四个时机）

四个进化时机（用户已确认全要）：
- 会话/任务收尾：回顾本轮，有没有「下次还会重复解释」的事？提成候选。
- 出错被纠正时：用户纠正你后，立刻把这条教训（带原因）记为候选。
- 手动审查：用户跑审查命令时，主动扫候选。
- Auto Memory 策展：跑 python scripts/memory_digest.py，从
~/.claude/projects/<proj>/memory/MEMORY.md 找反复出现 ≥2 次的模式。

升级流程（详见 evolution-playbook.md）：
1. 收集候选 → 2. 过准入门槛（答不上"不写会错什么"就丢弃）→ 3. 写成
「可执行 + 配反例 + 一句原因」的规则 → 4. 给用户看 diff 等确认 → 5. 最小 diff 写入
正确的文件（就近原则，见 orchestrate）→ 6. 若来自 auto-memory，确认已写进 CLAUDE.md 后
用 python scripts/graduate.py <记忆文件> [项目根]（默认 dry-run，加 --confirm 才删）从 memory
删除并清理 MEMORY.md 指针，腾出官方 200 行/25KB 预算。

🔴 CHECKPOINT（第 4 步，不可跳过）：写入任何 CLAUDE.md / 删除任何 memory 前，先把 diff 给用户、
等明确确认。hook 和脚本只产候选/dry-run，绝不自动改写 CLAUDE.md。graduate --confirm 前必须先
确认那条规则已升级进 CLAUDE.md，否则会丢失内容。

orchestrate —— 多 CLAUDE.md 定位与编排（monorepo）

0. 自省（先跑）：python scripts/introspect.py <项目根> [--editing <文件>] 输出"加载体检表"——
   会加载哪些 CLAUDE.md、合并多少字节（是否逼近 40000 告警线）、哪条 .claude/rules 的 paths glob
   会因编辑某文件触发、有无外部 @import 警告、AGENTS.md 是否已 @import。官方只有 /memory show，
   silk-starry 多了"预测某次编辑会附加哪些规则 + 字节预算"。
1. 定位：用户问"改 X 该看哪个"时，跑 python scripts/locate.py <文件路径>，
   按「就近原则」返回应读/改的 CLAUDE.md 链（从根到最近的子目录）。
2. 分层：根 CLAUDE.md 放跨仓共享规范（commit 格式、全局禁区、导航）；
   子模块 CLAUDE.md 放各自框架/测试/禁区。冲突时就近层权重更高——但别依赖加载
   顺序解决冲突，要保证规则不矛盾。
3. 导航索引：可用 assets/index-template.md 在根 CLAUDE.md 里生成"什么场景看哪个文件"
   的索引。
4. AGENTS.md 共存 / 跨工具同步：Claude Code 只读 CLAUDE.md。跑
   python scripts/sync_targets.py <项目根> 盘点各工具记忆文件并给打通建议；若已有 AGENTS.md，
   在 CLAUDE.md 顶部 @AGENTS.md import（可加 --add-agents-import 安全自动加），别复制两份。
   对 Cursor/Copilot 只生成指针、不复制全文（防漂移）。详见 orchestration.md。

失败兜底（显式分支，遇到就按这个走）

• generate 探测不出技术栈 → 用 templates/generic.md 起手，并问用户补确认栈，不要瞎猜。
• audit/generate 发现敏感信息（脚本报 🔴）→ 在报告/文件里只说"X 处凭证应移到 .env"，
  绝不把凭证原值复述进 CLAUDE.md 或报告。
• memory_digest.py 报"未找到 auto-memory 目录" → 多半是版本 <2.1.59 或路径推导错；
  让用户用 --memory-dir <dir> 显式指定，不要当作"没有可升级内容"。
• locate 返回"路径上没有任何 CLAUDE.md" → 转 generate 先建一个，别继续编排空气。
• conflicts 报冲突但其实是有意覆盖 → 确认子文件是否声明了"覆盖"，是则按有意覆盖处理、不强改。
• 脚本报错/超时 → 当作"未知"继续，不阻断；把失败如实告诉用户，别假装跑过。

四、脚本（确定性的事交给脚本，判断的事你来）

全部用 python（Windows 上不是 python3），UTF-8，只读不写（除非动作要求）。

脚本路径相对 skill 目录；从任意 cwd 调用时用 skill 的绝对路径。

五、轻量 Hook（实现"何时进化"，项目级，一键安装）

scripts/install_hooks.py 会把两个 hook 注册进目标项目的 .claude/settings.json
（不污染其他项目，与已有 hook 合并而非覆盖）：

• SessionStart：开会话时把"有 N 条待审升级候选 / CLAUDE.md 已 X 天未体检"注入上下文
  （只有 SessionStart/Stop 的 stdout 能回注）。
• Stop：本轮结束时若检测到反复纠正，追加候选到 .claude/silk-starry/candidates.jsonl
  （只记录，不改 CLAUDE.md），并提示下次运行 evolve。务必查 stop_hook_active 防死循环。

hook 脚本本体在 scripts/hooks/。安装前先告诉用户会改它项目的 settings.json。

六、🔴 红线 / 绝不做（违反任何一条都算事故）

• 🔴 绝不自动改写 CLAUDE.md / 删 memory——写入前必给 diff、等用户确认（hook 只产候选）。
• 🔴 绝不把读到的明文凭证（key/token/密码/内网 IP）复述进 CLAUDE.md 或报告——转写成"配置在 .env"。
• 🔴 绝不 graduate --confirm 删除尚未升级进 CLAUDE.md 的 memory。
• 🔴 绝不改动工具托管块（如 trellis 的 <!-- TRELLIS:START/END -->、被 codegen 生成的文件）。
• 🔴 绝不靠加载顺序"摆平"两条矛盾规则——暴露冲突让用户选一条，别取平均。
• 🔴 绝不把代码能看出来的东西（目录树/架构/技术栈版本）写进 CLAUDE.md。
• 🔴 绝不把规则塞进 CLAUDE.md 来当硬约束——硬约束（禁 push main 等）用 PreToolUse hook。

七、自检清单（每次写/改完 CLAUDE.md 都过一遍）

• [ ] 根文件 ≤200 行（理想 ≤60）？超了拆 .claude/rules/ 或 @import。
• [ ] 每条规则都能答上"不写会错什么具体的事"？
• [ ] 规则可自动执行、配了反例？
• [ ] 没有代码能看出来的内容（目录树/架构罗列）？
• [ ] 没有敏感信息（key/token/密码/内网 IP）？
• [ ] 禁区和"提交前必跑"命令写了吗？
• [ ] 改动是最小 diff、没顺手重排既有内容？