本项目 Claude Code 配置基线 + 新人上手

本页职责：在科技专题项目里用 Claude Code 的标准配置和新人上手。它顺带修掉几个真实诊断出来的洞：AGENTS.md 没被自动读到、0 个 hook、context7/serena 几乎没用。可分享：除"真实诊断数字"外，整套配置基线团队通用。配套流程见开发工作流 SOP。

A · 该装什么（插件 / MCP）+ 为什么

你已装 5 个 MCP，关键不是"装"，是"装了真用"——context7 调用 0 次、serena 才 ≈15 次（对比 Read 整文件 2098 次）是最大的浪费。

工具	干嘛用	为什么对本项目重要
serena	符号定位 / 找引用	Vue 大组件、SpringBlade 多层调用，用它比 Read 整文件准且省上下文
context7	查库/框架最新文档	写 Vue3 / ant-design-vue / SpringBlade 4.7 / Spring Boot 3.2 别信模型记忆，可能过时或编
figma	读设计稿	你有 `design-assets/*.fig`，还原设计稿直接喂
playwright	浏览器自动验证	前端改完自验（起 :8000 点一遍）
chrome-devtools	性能/内存调试	页面卡、LCP 慢、内存涨时用

落到习惯：找代码先想 serena，查框架写法先想 context7。这条写进了下面 D 节的工作约定。

B · 让项目文件真正被 Claude 读到（修真问题）

机制：CLAUDE.md 每次会话自动加载；AGENTS.md 默认不自动加载，除非被 @import 或你明确让它读。

现状（已核实）：根 CLAUDE.md 只在正文写了"通用导览见 AGENTS.md"，但没有 @import → 那 46 行通用约束其实没进上下文。4 份 AGENTS.md 都在（根 46 / kj-frontend 152 / SpringBlade_GKX_Base 132 / docs 190 行）。

修法：

根 CLAUDE.md 顶部加 @AGENTS.md（根那份只有 46 行，自动加载代价小）——让通用约束每会话生效。
子目录那三份（较大）维持现有"进哪个目录读哪个"的按需路由（CLAUDE.md 里那张路由表），别全 @import，否则每会话多加 ~470 行、撑大上下文。
进 kj-frontend/ 或后端目录干活时，开局 @kj-frontend/AGENTS.md / @SpringBlade_GKX_Base/AGENTS.md 手动带上。

草案见本页末尾「待你确认的配置改动」。

C · 红线兜底 hook（补 0 hooks + bypassPermissions）

现状：全局 bypassPermissions + skip*PermissionPrompt + 0 个 hook = 你写在 CLAUDE.md 里的红线（rm -rf/git push/改 settings 要确认）全靠自觉，没有硬闸。Bash 你跑了 4000+ 次，这道闸很值。

修法：在项目级 .claude/settings.json（团队共享，区别于你个人的 settings.local.json）加一个 PreToolUse hook，拦截红线 Bash 命令。草案见末尾。

注意：hook 是确定性硬闸（CLAUDE.md 是软约束），这正好补上 bypassPermissions 放开后的缺口。落地前用 /hooks 验证一下。

D · 工作约定写进 CLAUDE.md（让模型默认就对）

CLAUDE.md 已加了「交互习惯」段（放任句/审查无标准/盲放行时提醒你）。再补一条工具默认约定，治 context7=0 / serena≈0：

草案见末尾。核心两句：找代码默认用 serena，查第三方库/框架写法默认用 context7。

E · 新人 5 分钟上手（可照抄）

装工具：装上 serena / context7 / figma / playwright / chrome-devtools（/plugin 里装或确认已启用）。

前端跑通：

bash

cd kj-frontend && pnpm i && pnpm dev    # 起 :8000，浏览器打开能登录即 OK

后端编译：

bash

cd SpringBlade_GKX_Base && mvn -q -DskipTests compile   # 起 Nacos/Redis/微服务在 Mac 上由 codex 做

读约束：CLAUDE.md（已 @import 根 AGENTS.md）会自动加载；进子目录干活带上对应 AGENTS.md。
第一个任务：照开发工作流 SOP 的"完整功能开发流程"走；放任/审查/大改按学习路径的习惯来。
装自查 skill：把 data/cc-habits-SKILL.md 放到 .claude/skills/cc-habits/SKILL.md，干活时 /cc-habits 调出自查卡。

配置基线 Checklist（团队可勾）

[ ] serena / context7 / figma / playwright / chrome-devtools 已装并能用
[x] 根 CLAUDE.md 已 @import AGENTS.md（已应用）
[x] 项目 .claude/settings.json 有红线 PreToolUse hook（已应用，待你 /hooks 验证）
[x] CLAUDE.md 有「交互习惯」段 + 「工具默认（serena/context7）」约定（已应用）
[ ] 前端 pnpm dev 起得来、后端 mvn compile 过
[ ] 装了 /cc-habits 自查 skill

这套文档怎么分享给团队（两层结构）

整站分两层，分享时只给"通用层"：

层	包含哪些页	能否分享
通用层（可直接分享）	官方手册、大佬操作手册、开发工作流 SOP、决策指南、本配置基线、学习路径的方法部分、改写练习	可，团队通用
我的复盘层（个人，含真实数据）	改进清单、深度复盘、逐条处理、全部历史、全量 Prompt 审查、会话精修	否，含我的真实数据

分享前脱敏 3 步：

不分享"我的复盘层"那几页（它们全是你的真实历史/数字）。
通用层页里标了「你的真实例子 / 你的真实差距 / 你的现状」的小段——分享时删掉或换成团队自己的（这些段当初就独立标注，方便删）。
散落的真实数字（空转 33.7%、151 次调用等）属于个人复盘，别随通用页外发。

一句话：通用层 = "怎么用 Claude Code"（可分享）；复盘层 = "我用得怎么样"（自留）。

维护与刷新（让这个站不过期）

这个站有时效性，过期 = 慢慢变成误导。定期刷新才一直有用、也才对得起"零编造"的底线。

哪些会过期：

个人数据页（改进清单、深度复盘、逐条处理、全部历史、Prompt 审查、会话精修，以及学习路径的数字、决策指南的"你的现状"）——来自 ~/.claude/ 真实历史，随你使用持续变化。
官方手册（103 页）——官方文档更新后会漂移。

刷新频率：个人数据每月一次（配合成绩单看趋势）；官方手册按需或官方大版本更新时。

一键刷新（个人数据 + 成绩单）：

bash

cd claude-code-learn
node scripts/mine-evidence.mjs && node scripts/classify-and-stats.mjs   # 重挖真实历史 + 重算分层/频次
node scripts/measure.mjs                                                # 打印成绩单（空转%/放行/追问 的最新值与趋势）

逐条处理页（773 条）要纳入新会话时，再跑团队流水（量大、烧 token，按需）：

bash

# 1) 重新准备喂料 → 2) 跑 wf-history.mjs（Workflow）处理新会话 → 3) 校验 → 4) 装配 → 5) 重建
node scripts/prepare-worker-input.mjs
# （Workflow: scripts/wf-history.mjs，处理新增 sessionId）
node scripts/validate-processed.mjs && node scripts/build-history-pages.mjs && node scripts/gen.mjs
npm run docs:build

官方手册刷新：改 data/*.json（或重跑研究）→ node scripts/gen.mjs。

防腐习惯：

个人数据页统一标 "快照：YYYY-MM"（改进清单已带，其它页重大刷新时补上）。
每月跑一次 measure.mjs，若某页数字和当前差很多 → 刷新或在页首加"截至 X 月"。
重看时先看成绩单趋势（空转% 在降说明练习见效），再决定哪页要更新。

已应用的配置改动（2026-05）

下面 ①②③ 已落地（未碰全局 ~/.claude/settings.json）。③ 的 hook 请在你的真实会话里用 /hooks 确认生效、随便跑条普通命令确认没被误拦（hook 在你 Mac 的 Claude Code 里才触发，容器内验不了）。

① 根 CLAUDE.md 顶部加 @import（让 46 行通用约束自动加载）— 已应用

markdown

本仓库通用导览与跨工具约束见 @AGENTS.md（自动加载）。本文件仅追加 Claude Code 特有的工作规范。

② CLAUDE.md 补一条"工具默认"约定（接在「交互习惯」段后）— 已应用

markdown

## 工具默认（治我 context7=0 / serena≈0 的毛病）
- 找"某函数/类在哪定义、被谁调用"：默认用 serena（find_symbol / find_referencing_symbols），别 Read 整文件再 grep。
- 写/查第三方库或框架（Vue3 / ant-design-vue / SpringBlade / Spring Boot）写法：默认用 context7，别凭记忆。

③ 新建项目级 .claude/settings.json（团队共享）+ 红线 hook — 已应用（用 fail-open 写法）

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "cmd=$(jq -r '.tool_input.command // empty' 2>/dev/null); if printf '%s' \"$cmd\" | grep -Eq 'rm[[:space:]]+-rf|git[[:space:]]+push[[:space:]]+(-f|--force)|git[[:space:]]+reset[[:space:]]+--hard|pnpm[[:space:]]+remove|npm[[:space:]]+uninstall'; then echo \"红线命令，需人工确认后手动执行：$cmd\" >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

拦截：rm -rf、git push --force/-f、git reset --hard、pnpm remove、npm uninstall。exit 2 = 拦下并把原因回给 Claude。（落地时实测有效——它当场拦下了一条含该路径的命令；据此已收窄：plain git push 不拦（由 CLAUDE.md 约定管），去掉了"提到 settings.json 就拦"的过宽规则。按需再调正则。）

①②③ 均已落地。下一步只剩你做一件：在真实会话里 /hooks 确认 ③ 生效、随便跑条普通 Bash 确认没被误拦；正则想收紧/放宽就改 .claude/settings.json。

本项目 Claude Code 配置基线 + 新人上手 ​

A · 该装什么（插件 / MCP）+ 为什么 ​

B · 让项目文件真正被 Claude 读到（修真问题） ​

C · 红线兜底 hook（补 0 hooks + bypassPermissions） ​

D · 工作约定写进 CLAUDE.md（让模型默认就对） ​

E · 新人 5 分钟上手（可照抄） ​

配置基线 Checklist（团队可勾） ​

这套文档怎么分享给团队（两层结构） ​

维护与刷新（让这个站不过期） ​

已应用的配置改动（2026-05） ​

本项目 Claude Code 配置基线 + 新人上手

A · 该装什么（插件 / MCP）+ 为什么

B · 让项目文件真正被 Claude 读到（修真问题）

C · 红线兜底 hook（补 0 hooks + bypassPermissions）

D · 工作约定写进 CLAUDE.md（让模型默认就对）

E · 新人 5 分钟上手（可照抄）

配置基线 Checklist（团队可勾）

这套文档怎么分享给团队（两层结构）

维护与刷新（让这个站不过期）

已应用的配置改动（2026-05）