📝 主旨内容

1. 写“短而狠”的规则（建议行数上限）

C:\Users\abely\.claude 这个文件夹可以在这里，也可以是项目当中，属于Minimal, opinionated files/ystem

• ~/.claude/CLAUDE.md（≤120 行）：全局工作原则、输出格式约束、工具使用约定。

• ~/.claude/projects/<your-repo>/CLAUDE.md（≤80 行）：只写本项目的特例（技术栈、目录约定、测试与迁移底线）。

• output-styles/default.md：定义默认输出风格（先给变更清单再给补丁、错误只给 1 行原因 + 1 行修复）。

• commands/：把常用动作（/go、/plan、/implement、/codefind、/docgen、/refactor）写成简短步骤，可一键调用。

• hooks/：例如在消息里出现“增强 prompt”时自动注入 guides/prompting-guide.md 的提示；拦截超大 MCP 负载。

• projects/<repo>/docs/：**长期记忆与决策（ADR）**全放这里，后续对话只引用路径而不复制全文。

• projects/<repo>/agents/：前端、后端、codefinder 等子代理系统提示，每个 10～30 行，范围越窄越好。

1. 运行仪式（推荐流）

• 新对话/docgen：先把新特性写成 docs（需求、接口契约、约束）。

• 新对话 /plan：读取 docs 产出并行任务计划，保存到 docs/plan/*.md。

• 新对话 /implement：按计划给每个子代理最小上下文执行，输出补丁与测试。

• 最后 /refactor + 更新 docs/ADR。

1. 实用“尺寸红线”

• 顶层 CLAUDE.md ≤120 行；项目内 CLAUDE.md ≤80 行；每个 command/hook/agent 力求一屏可读。

• MCP 工具返回做压缩 Markdown（表格/简短代码块），禁止长堆栈；单次工具输出建议 ≤64–128 KB。

• 对话上下文 > ~60–80k token 就开新对话，只带路径与摘要。

2. 对于Claude code的输出规则（Output style）

~/.claude/output-styles/default.md output style（输出风格）就是一份“格式与习惯”的说明书，用来约束 Claude 在每次回复时怎么组织内容。

• 省 Token：固定为“精简摘要 → 补丁/表格 → 后续行动”，避免啰嗦。

• 稳定可读：团队收到的输出结构一致，便于审阅与上 CI。

• 可切换语气：不同场景换不同风格（如“ship-fast”更短更干脆）。

• 路径：~/.claude/output-styles/<name>.md（如 default.md、ship-fast.md）

• 切换：在 CC 里执行 /output-style:<name>（或 /output-style:new 描述 新建后再编辑）

• CLAUDE.md：做什么/底线（原则、流程、工具约定）

• output style：怎么说（结构、顺序、格式、长短）

• Slash 命令：何时触发什么流程（/plan、/implement 等）

• 不带风格：长段落解释 + 零散代码片段 → 难读、难审

• 带风格：
1. 摘要（做了啥/为什么）
2. 变更清单（哪些文件、每个 1 行理由）
3. 补丁（统一 diff）
4. 下一步（最多 5 条）

3. Token rules you can actually follow（可真正执行的 Token 规则）

原理 → 指标线 → 操作手册 → 常见坑 → 速查表。 原理（为什么要管 Token）

Claude 的“上下文”= 系统提示 + 你的对话历史 + MCP 工具输出 + 读入的代码/文档。

当上下文太胖时：规划变慢、幻觉增多、逻辑被早期噪声“锁死”。所以要像管内存一样精打细算。

指标线（记住这几条就够）

• 总上下文软上限：60–80k tokens → 超过就开新对话（只带路径/摘要，不搬全文）。

• MCP 工具输出总量：≤20k tokens → 工具啰嗦会**“挤掉”真正写代码的空间**。

• 单次工具返回建议 ≤64–128 KB 文本（做压缩 markdown：表格/短代码块）。

• 文档与历史 = 长期记忆 → 放 docs/*.md，对话里只给指针（路径）。

操作手册（怎么落地）

1. 分阶段新对话（强制切割上下文）
• 规划（/plan）完成 → 新对话做实现（/implement）
• 实现合并后 → 新对话做复盘/重构（/refactor）
• 每次只带：docs/plan/xxx.md、相关文件路径、关键约束摘要（非全文）

2. 把冗长信息外置化
• 需求、决策、规范 → docs/ 下的 md
• 工具/命令用法 → guides/ 下的 md
• 让 Claude “读路径”，而不是“贴全文”

3. 压瘦 MCP 工具输出
• 只保留表格/短块；去掉堆栈长文
• 统一格式：
• 真的很长 → 存文件，只回文件路径

• 最小必要代码上下文
• 先用“codefinder 子代理”找**≤8 个文件**入口 + 关键符号
• 只读这些文件片段；禁止“一口吞整个目录”

• 输出也要省
• 代码改动用 diff --git，不要整文件粘贴
• 新文件：先目的/清单，再给内容；>200 行就分块/存文件

• 固定清理节奏
• 对话 token > ~60k → 新建
• 本轮工具输出累积 > ~15–20k → 关非必要工具/改为落盘
• 发现“计划反复改、思路发散” → 保存计划 md，新对话再执行

常见坑（以及替代做法）

• 坑：把 README、长日志、API 文档贴进对话
**改：**落盘到 docs/，对话只传“要点 + 链接路径”

• *坑：**安装“全家桶”MCP（几十个工具）
改：自制最小 MCP（2–3 个常用工具），输出压缩 markdown

• 坑：在同一聊天里又规划又实现又复盘
改：每个阶段新对话，带指针不带全文

• 坑：一次性把大型代码库全量喂给 Claude
改：先 /codefind 找入口，再逐步按需读取

速查表（贴墙上用）

• 总上下文 > 60–80k？ → 新对话

• MCP 输出 > 20k？ → 关掉/压缩/落盘

• 输出太啰嗦？ → 切到 ship-fast 输出风格（摘要 + diff）

• 找不到入口？ → 先跑 /codefind（≤8 文件 + 符号清单）

• 计划越写越长？ → 保存到 docs/plan/*.md，新对话执行

4. Slash-commands（可直接放进去用的斜杠命令）

在 Claude Code 里，Slash-command 就是你自己定义的一段“标准操作流程（SOP）提示词”，保存为一个 markdown 文件，放进 ~/.claude/commands/。

当你在对话里输入 /plan、/implement 等时，Claude 会把对应文件内容当作提示注入，从而按你规定的步骤输出，避免临场长篇提示。

一句话：把“长提示”产品化，按命令一键调用，输出可复用、可审阅、可落盘。

为什么用

• 省 Token / 稳定产出：统一结构与约束，避免每次临时编长提示。

• 流程标准化：把“规划→实施→文档/复盘”变成固定仪式，减少跑偏。

• 支持并行/子代理：命令里直接规定如何委派给子代理（frontend/backend/codefinder）。

• 可团队共享：一份命令多人用，审阅成本更低。

怎么放（文件与命名）

• 目录：~/.claude/commands/

• 文件名要包含前导斜杠，例如：
• ~/.claude/commands//plan.md → 触发 /plan
• ~/.claude/commands//implement.md → 触发 /implement
• ~/.claude/commands//codefind.md → 触发 /codefind
• ~/.claude/commands//docgen.md → 触发 /docgen

• 内容：一份简短但严格的步骤说明（前面我已给了可直接用的范本）。

备注：之所以文件名带一个真正的“/”，是为了让命令名与文件名 1:1 对应，输入更直觉。

怎么触发与使用节奏

1. /docgen：为新功能创建/更新文档（docs/feature-X/*），把长期记忆放进 md。

2. 新聊天 → /plan：读取 docs 与 ADR，产出并行任务清单，并把计划落盘 docs/plan/<feature>.md。

3. 新聊天 → /implement：按计划为每个 bucket 派发子代理执行，输出 diff 补丁 + 最小测试。
（结束后可 /refactor 做机械化重构与收尾）

每个命令在做什么（职责与输入输出）

/plan（规划模式）

• 输入：docs/index.md、docs/feature-*/、docs/adr/*（只读摘要与路径）

• 动作：
1. 通过 codefinder 子代理锁定 ≤8 个入口文件与关键符号
2. 产出 Parallel Buckets（可并行的任务桶）
3. 汇总 Invariants（来自 ADR 的不可违反约束）
4. 列出 Artifacts（代码与文档将写入的精确路径）
5. 把计划落盘：docs/plan/<feature>.md（≤150 行）

• 输出风格：短摘要 + 任务表；避免一次性贴大段代码/文档。

/implement（实施/委派）

• 输入：docs/plan/<feature>.md + Invariants 路径

• 动作：
1. 为每个 bucket 派生子代理（frontend/backend 等），只给其最小上下文
2. 子代理返回：
• diff --git 补丁
• 新/更文档的路径
• Postconditions / 测试改动
3. 汇总、检测冲突，必要时提出微型调和计划再改

• 输出风格：变更清单 + 补丁；>200 行落盘给路径。

/codefind（代码勘察）

• 输入：你的问题 + 粗略线索（模块/目录名等）

• 动作：
• 返回 ≤8 个候选文件 + 每个 1 行理由
• 返回 关键符号 与定位
• 如果还不够，给 ≤3 个下一步读取建议

• 输出限制：总 ≤300 行（严格控量，防上下文膨胀）。

/docgen（文档生成/对齐）

• 动作：在 docs/feature-<name>/ 下生成或更新：
• index.md（概览、用户故事、契约）
• context.md（组件/数据流）
• decisions.md（链接 ADR）
• checklist.md（完成/未完成）

• 规则：每个文件 ≤150 行；尽量链接而非粘贴长文。

你也可以加 /refactor（机械化重构）、/review（审查清单）、/hotfix（快速修补）等命令，思路相同：短步骤 + 强约束。

进阶技巧

• 与 output-style 联动：触发 /plan 前先 /output-style:default；到了合并/落地阶段切 /output-style:ship-fast（只要补丁）。

• 参数化：你可以在命令开头要求“请先询问本次 <feature> 名称与目标”，把用户回答落盘到 docs/plan/<feature>.md 的 frontmatter。

• 与 hooks 联动：在 on_message_created.sh 中检测关键字，自动注入 guides/prompting-guide.md 或提醒“上下文超限请新建对话”。

• 与子代理配合：/implement 内部规定“每个 bucket 只给相关文件路径 + Invariants 摘要”，保证最小上下文，提升稳定度与速度。

• 最小化 I/O：命令里明确“输出统一为 diff + 路径”，把长文本落盘，避免把对话当文件系统。

常见坑 & 规避

• 命令写太长/太松散 → 规则越短越好（一屏可读），越能稳定产出。

• 在同一聊天里连跑 /plan→/implement → 容易把规划中间产物塞爆上下文，阶段要新开聊天。

• codefinder 一次性读太多 → 限制 ≤8 个文件；不足再迭代勘察，而不是一口吞。

• 输出不是 diff → 统一用 diff --git，便于审阅与自动应用。

• 未落盘 → 计划与文档必须落盘到 docs/，否则记忆会丢。

贴心小抄（你当前栈）

• Next.js 前端：在 /implement 的 frontend 子代理里要求：新增组件必须附最小 Storybook/测试片段或手测步骤。

• Supabase / Postgres：backend 子代理要求每次 schema 改动同时给迁移+回滚脚本，并写入 docs/adr/ 的决策记录。

• n8n 工作流：把工作流导入/导出路径也写进 docs/；变更通过 /plan 先决策节点与队列，再实施。

5. Hooks = Claude Code 的“拦截器/自动化脚本”。

把脚本放到 ~/.claude/hooks/，在特定时机自动执行，用来：

• 统一注入提示（例如提示先读某份指南）

• 拦截/修改工具调用负载（例如禁止 fallback、限制体积）

• 规范工具输出（太长就落盘，只回路径）

• 打标签、记日志、度量 token

何时触发（对应示例）

• on_message_created.sh：当你发出一条消息后立刻触发（输入阶段）

• on_before_tool_call.sh：Claude 要调用 MCP 工具的前一刻（前置拦截）

• on_after_tool_call.sh：MCP 工具返回之后（后置处理）

为什么要用

• 省 Token：把重复性“提示/文档”改为按需自动注入

• 控质量：统一禁止“兜底 fallback”、超长堆栈、啰嗦输出

• 提效率：关键字触发工作流（如提到“增强 prompt”就自动附上指南路径）

• 可治理：对每次工具调用做体积/频率限制，避免“上下文爆仓”

6. Subagents (keep system prompts tiny)子代理用法

子代理 = 专职小模型/小角色。主代理只负责计划与编排，把具体工作委派给多个“聚焦且系统提示极短的小代理”。这样每个子代理拿到干净的新上下文，减少“被历史污染”的风险，同时更省 token、更稳。

何时用（判定三条件）

• 可并行：前端 UI、后端 API、脚手架/配置、文档/ADR 可拆桶并行推进

• 领域明确：某类任务需要固定风格/底线（如前端可访问性、后端迁移+回滚）

• 上下文庞大：主对话已接近 60–80k tokens，需要“刷新上下文”来执行

怎么拆工（三个常用子代理）

• Frontend 子代理：只改 UI/样式/可访问性；输出最小 diff + Storybook/测试片段

• Backend 子代理：只改 API/Schema/Jobs；强制迁移+回滚脚本+最小验证步骤

• Codefinder 子代理（侦察兵）：不改代码，只返回 ≤8 个文件入口 + 关键符号 + 下一步读取建议

还有可选：Docs 子代理（整理 docs/ 与 ADR），DevOps 子代理（CI/CD、Traefik/Dokploy 配置）

传递最小上下文（Handoff Packet 格式）

子代理系统提示模板（极短版）

放在 ~/.claude/projects/<repo>/agents/*.md，每个 10–30 行

backend.md

backend.md

• Bucket A（Frontend）：Next.js 页面/组件、Tailwind/Radix、可访问性

• Bucket B（Backend）：Supabase SQL/Edge Functions、RLS、迁移+回滚

• Bucket C（n8n）：工作流 JSON、节点参数校验、导入导出路径

• Bucket D（Docs）：docs/feature-X/*、docs/adr/* 更新

• 数据库：任何表结构变更 → 必有 migrations/<ts>_*.sql 与 rollback_<ts>_*.sql

• 前端：新增组件必须附 Storybook/测试或说明步骤

• n8n：工作流导出为 docs/flows/<name>.json，校验哈希

• Traefik/Dokploy：只输出 label 变更 diff；证书解析采用现有 resolver 名称

主代理怎么编排（实践步骤）

1. 新对话 → /codefind：先勘察入口文件与关键符号（≤8）

2. /plan：生成并行 Buckets + Invariants + Artifacts，落盘 docs/plan/<feature>.md

3. 新对话 → /implement：逐 bucket 派发给对应子代理
• 附上 Handoff Packet（目标/约束/入口/产物/测试/风格）
• 强制使用 ship-fast 输出风格（摘要 + diff）

4. 汇总补丁，若冲突 → 生成微型调和计划再改

5. 验证 & 文档更新（可由 Docs 子代理执行）

常见坑 & 规避

• 系统提示太长：子代理提示要“越短越好”。领域约束写进 Invariants，不是堆在系统 prompt。

• 给了整段历史：只传 指针+摘要。大文本落盘，路径引用。

• 子代理边界不清：明确 Scope；Frontend 不动后端；Backend 不动 UI。

• 一次塞太多文件：入口 ≤8；不足再迭代。

• 输出不是补丁：统一 diff --git，便于审阅与自动应用。

• 没测试/迁移：把“测试最小增量”“迁移+回滚”写进 Invariants，缺失就当失败重试。

速查表

• 何时用：可并行 / 领域明确 / 上下文过胖

• 关键做法：主代理计划，子代理执行；传指针不传大段文本

• Handoff Packet：Goal / Invariants / Entrypoints / Artifacts / Tests / Output Style

• 三大子代理：Frontend / Backend / Codefinder（可加 Docs/DevOps）

• 硬性要求：diff-only、≤8 文件入口、迁移+回滚必备、长文落盘

7. 极简 MCP 模式：超压缩 Markdown 输出）

“Minimal MCP”的意思是：只暴露 2–3 个最常用工具，并且所有返回一律是超短 Markdown（标题 + 若干行 + 小表格/小代码块），把长内容落盘或截断，从源头控制 Token 体积与格式稳定性。

为什么要这么干

• 省 Token：默认/全家桶 MCP 一次能喷出几万 Tokens；极简输出把每次调用压到 64–128KB 以内。

• 稳定可读：统一成同一排版，便于你后续自动处理（审阅、粘补丁、上 CI）。

• 可控：你自己写/裁剪工具，错误只给 Cause/Fix 两行；堆栈与大对象不进上下文。

具体怎么做（通用规则）

1. 只保留 2–3 个工具（例如 fs.read、db.query、kv.get/set 或 http.fetch）。

2. 统一输出协议（所有工具都照下面格式）：

3. 强截断/分页：
• 文本 > 200 行 → 只给前 200 行 + (truncated) 标记；全文落盘再返回路径。
• 表格只回 前 50 行。
• 单次响应 ≤64–128KB；超限就落盘并在 Summary 说明。

4. 错误两行制：不回堆栈，只回 Cause & Fix。

5. 输入白名单：限制参数（允许的路径、允许的 SQL 动词、域名白名单等），默认拒绝。

7. 每个阶段“新开聊天”+ 只传文件路径指针，让上下文随时“焕新”。

把大改动拆成三个独立对话阶段：先把知识沉到 md 文件（Doc），再用最小上下文生成并行计划（Plan），然后用子代理按桶实施（Implement），合并后Refactor收尾、Docgen更新决策。

每一步做什么（操作手册）

1) /docgen（先文档，后编码）

• index.md：背景、目标、用户故事、成功指标

• context.md：范围、组件/数据流草图、外部依赖

• contracts.md：接口/DB 契约（只列关键点与路径）

• risks.md：已知风险与回滚思路

• （可选）checklist.md：完成/未完成

之后所有阶段只引用路径，不再粘贴长文。

2) 新聊天 → /plan（并行计划，落盘）

1. 先 /codefind 勘察：列出 ≤8 个入口文件与关键符号

2. 产出 Parallel Buckets：每个包含 {name, objective, entrypoints, tests, risks, est}

3. 汇总 Invariants：来自 ADR/安全/数据一致性的不可违反约束（≤8 条）

4. 列出 Artifacts：将要写入/更新的精确路径（代码与文档）

3) 新聊天 → /implement（按桶分派子代理）

• 对每个 bucket 发送 Handoff Packet（只含指针与摘要）：

• 强制输出 diff --git 补丁 + 最小测试/验证步骤；>200 行内容落盘给路径

• 汇总补丁，若冲突，先给微型调和计划再改

4) 合并后 /refactor → 再 /docgen 更新

• /refactor：小心翼翼的结构/命名/去重，只出最小 diff，附测试更新

• /docgen：把新增的决策写入 docs/adr/，更新 docs/feature-<name>/*

为什么有效（原理）

• 新鲜上下文：每个阶段新开聊，旧噪声不再“锁死”后续思路

• 最小系统提示：子代理提示极短；复杂约束放在 Invariants/ADR 路径

• 指针而非长文：聊天里只传“路径/摘要”，把 Token 留给真正的代码生成

• 天然并行：Buckets 让前后端/工作流/文档同时推进

• 可审计：所有关键产物落盘，历史可追踪、好复盘

7. Copy-paste starters

C:\Users\abely\.claude 这个文件夹可以在这里，也可以是项目当中，属于Minimal, opinionated filesystem

📎 参考文章

• 一些引用

• 引用文章