claude-code-setup 实战：把 Claude Code 从聊天工具变成工程系统claude-code-se

最近整理了一批关于 claude-code-setup 的笔记，里面有安装、入口冲突、Hooks 配置、Skills 解释，以及一个 iOS 项目的真实推荐案例。

把这些内容放在一起看，结论很明确：

claude-code-setup 不是让 Claude Code “更会聊天”的插件。

它真正做的是：

把你的项目升级成适合 AI Agent 长期协作的工程系统。

这件事很关键。因为现在很多 AI coding 的失败，不是模型完全不会写代码，而是它每次进入项目都像一个刚入职、没有 onboarding、没有代码规范、没有测试入口、没有权限边界的新同事。

你让它改一个功能，它能写。你让它连续维护一个项目三个月，问题就开始越来越多。

先说清楚：它不是 `claude-code setup`

很多人第一步就会卡住。

安装命令通常是：

/plugin install claude-code-setup@claude-plugins-official

但它不是一个这样的 CLI 子命令：

claude-code setup

它是 Claude Code 的 plugin system 里的插件。按照 Claude Code 的插件机制，插件可以带来 Skills、commands、agents、hooks、MCP servers 等能力，而且插件命令通常会被 namespace 保护，避免和其他插件冲突。

所以你看到的入口可能不是 /setup，而是类似：

/claude-automation-recommender

如果你刚安装完插件，先执行：

/reload-plugins

再回到项目目录里运行推荐入口。不要一上来就找 /setup，因为 /setup 很可能已经被别的插件占用了。

它到底分析什么？

claude-code-setup 的目标不是直接帮你重构项目。

官方插件页对它的描述很清楚：它会分析 codebase，然后推荐适合当前项目的 automations，比如 hooks、skills、MCP servers 和 subagents。它的工作模式更接近一个只读的工程顾问，而不是直接动手改文件的代码生成器。

这点很重要。

因为好的 AI coding setup，不应该第一步就自动生成一堆复杂配置。它应该先读项目：

• 这是 iOS、Java backend，还是 Vue admin？
• 项目里有没有双语本地化？
• 有没有 StoreKit、Supabase、Photos、OCR 这类高风险模块？
• 当前有没有稳定的 build/test/lint 命令？
• 哪些文件不能让 AI 随便改？
• 哪些重复流程可以沉淀成 Skill？

没有这些信息，AI 加速只会把混乱放大。

裸用 Claude Code 的问题

拿一个真实场景说。

假设你在做一个 iOS App，例如 ShotZen，要实现“过期截图自动识别”：

• 机票截图
• QR Code
• 优惠券
• 外卖取餐码
• 物流页面

第一次你让 Claude Code 写 Vision OCR，它可能表现不错。

第二次你让它加缓存，它开始忘记你的 Repository pattern。

第三次你让它加 subscription gate，它可能绕过你封装好的订阅服务，直接去碰 RevenueCat 或 StoreKit。

第四次你让它补测试，它不知道你怎么 mock Photos framework，也不知道你项目的 SnapshotTesting 规范。

最后你每天都在重复：

Remember:- use MVVM- use async/await- don&#x27;t touch PurchaseManager directly- analytics use snake_case- don&#x27;t access Photos on main thread

这不是高效开发。

这是你在手动维持 AI 的短期记忆。

真正的入口是 `CLAUDE.md`

在已有项目里接入 claude-code-setup，我不建议第一步就追求全自动。

真正应该先做的是建立项目级上下文：

ShotZen/├── .claude/│   ├── CLAUDE.md│   ├── project-structure.md│   ├── architecture.md│   ├── coding-rules.md│   └── workflows.md

其中最重要的是 CLAUDE.md。

它不是项目 README。

README 是写给人看的。CLAUDE.md 是写给 AI 执行的。

不要只写：

This app cleans screenshots.

更有价值的是写约束：

# ShotZenShotZen is an iOS screenshot cleaner app.Core principles:- screenshot-first- privacy-first- on-device only- no cloud uploadTech stack:- SwiftUI- MVVM- async/await- Photos framework- Vision OCRRules:- Never scan the full photo library unless explicitly requested.- Never block the main thread during Photos or OCR work.- All analytics events use snake_case.- Never access RevenueCat directly inside Views.- Premium checks must go through SubscriptionService.- Use Repository pattern for data access.

这里的重点不是“介绍项目”，而是给 AI 一个操作系统级别的约束环境。

AI 最缺的不是信息。

AI 最缺的是边界。

Skills：把重复流程封装成 AI 命令

Skills 解决的是另一个问题：

不要每次都重新解释同一个流程。

比如一个中英双语 iOS 项目，每次加功能都要同时改：

zh-Hans.lproj/Localizable.stringsen.lproj/Localizable.strings

裸用 Claude Code 时，你可能会反复提醒：

记得两个语言都要加，不要只加中文。

更好的方式是做成一个 Skill：

---name: add-localizationdescription: Add a localization key to both zh-Hans and en Localizable.strings files---Add the following entry to BOTH localization files:- SpeechNote/zh-Hans.lproj/Localizable.strings- SpeechNote/en.lproj/Localizable.stringsFormat:"key" = "value";Arguments:  Read both files first. Verify the key does not already exist.Append under a matching comment section if possible, otherwise append at the end.

以后你只需要：

/add-localization "recordingFailed" "录音失败" "Recording failed"

这就是 Skills 的本质：

把高频、易漏、需要遵守项目习惯的流程，变成可复用的 AI 命令。

同理，ios-build 也很适合做成 Skill。

很多 iOS 项目的 build 命令很长：

xcodebuild -workspace SpeechNote.xcworkspace \  -scheme SpeechNote \  -destination &#x27;platform=iOS Simulator,name=iPhone 16&#x27; \  build

你不应该每次都让 AI 猜 workspace、scheme 和 simulator。

应该把它固定下来。

Hooks：让 AI 改完以后立刻接受反馈

Hooks 解决的是验证闭环。

很多 AI coding 翻车，根因是：

修改↓不验证↓继续修改↓错误叠加↓最后才发现第一步已经坏了

在 Claude Code 里，Hooks 可以在工具调用前后自动执行脚本。

比如 PostToolUse 可以在 Claude 编辑 Swift 文件后立刻做语法检查：

{  "hooks": {    "PostToolUse": [      {        "matcher": "Edit",        "hooks": [          {            "type": "command",            "command": "FILE=$(echo &#x27;$CLAUDE_TOOL_OUTPUT&#x27; | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d.get(&#x27;filePath&#x27;,&#x27;&#x27;))\" 2>/dev/null); [[ \"$FILE\" == *.swift ]] && swiftc -parse \"$FILE\" 2>&1 | grep error: || true"          }        ]      }    ]  }}

这不是完整编译，只是 Swift 语法解析。

好处是快。

Claude 刚改完一个 Swift 文件，如果少了一个 }，几秒内就能知道，而不是等 10 分钟以后跑完整 build 才发现。

PreToolUse 则适合做安全拦截。

比如阻止 AI 修改生产配置：

{  "hooks": {    "PreToolUse": [      {        "matcher": "Edit|Write",        "hooks": [          {            "type": "command",            "command": "echo &#x27;$CLAUDE_TOOL_INPUT&#x27; | python3 -c \"import sys,json; d=json.load(sys.stdin); f=d.get(&#x27;file_path&#x27;,&#x27;&#x27;); exit(1 if &#x27;Config.plist&#x27; in f else 0)\" && echo &#x27;BLOCKED: Config.plist contains production credentials. Edit manually.&#x27;"          }        ]      }    ]  }}

这类 Hook 的价值不是“显得高级”。

它是在给 AI agent 加工程保险丝。

MCP：让 AI 查事实，而不是靠记忆硬猜

MCP 适合放在第三阶段。

原因很简单：如果项目规则本身还没梳理好，直接堆 MCP 只会让系统更复杂。

但当你已经有了 CLAUDE.md、Skills 和 Hooks，MCP 的价值会非常明显。

比如 iOS 项目可以优先考虑：

• Apple Docs / Context7：查 SwiftUI、Photos、Vision、StoreKit 文档
• GitHub：看 issue、PR、CI 状态
• Supabase / PostgreSQL：分析数据表、同步状态、权限问题
• SQLite：检查本地缓存和迁移

模型记忆会过期。

项目事实不会因为模型语气坚定就自动正确。

所以需要 MCP 把外部事实接进来。

Subagents：不要太早上多智能体

Subagents 很强，但我不建议一开始就上。

很多人顺序错了：

multi-agentMCPautomation

然后项目里没有 CLAUDE.md，没有 coding rules，没有 build command，没有测试入口。

这种情况下，多智能体不是协作，是多路并发制造混乱。

更合理的顺序是：

第一阶段：CLAUDE.md第二阶段：Skills第三阶段：Hooks第四阶段：MCP第五阶段：Subagents

当基础规则稳定以后，再拆分角色才有意义。

例如一个 iOS 产品可以这样拆：

ios-agent- SwiftUI- Photos- OCR- performancesecurity-reviewer- API key- Keychain- StoreKit 2- Supabase auth- receipt validationlocalization-checker- zh-Hans keys- en keys- unused keys- missing translationsaso-agent- App Store metadata- screenshots copy- keyword density- conversion optimization

这时候你不再是“问一个通用 AI”。

你是在调用一组有边界、有职责、有项目上下文的专门 Agent。

一个推荐接入流程

如果你已经有一个长期维护的项目，我建议这样做。

第一步，安装并刷新插件：

/plugin install claude-code-setup@claude-plugins-official/reload-plugins

第二步，进入项目目录，运行 automation recommender：

/claude-automation-recommender

如果你的环境里显示的命令名不同，以 /help 或插件列表里实际展示的命令为准。

第三步，不要立刻照单全收。

先把推荐分成四类：

类别	先做什么	暂缓什么
CLAUDE.md	项目原则、架构规则、禁止事项	大段背景故事
Skills	高频重复流程	低频一次性命令
Hooks	快速语法检查、危险文件拦截	很慢的全量 CI
MCP	官方文档、GitHub、数据库	暂时用不到的外部系统

第四步，只落地 1-2 个最高价值自动化。

比如：

• 一个 ios-build Skill
• 一个 Swift 语法检查 Hook
• 一个禁止修改生产配置的 PreToolUse Hook
• 一个 localization checker agent

不要一次性生成 30 个东西。

AI coding 的工程化，不是配置越多越好。

它看的是反馈回路是否变短，错误是否更早暴露，项目规则是否能跨 session 复用。

常见坑

第一，不要把 CLAUDE.md 写成公司官网介绍。

AI 不需要品牌故事。它需要知道哪些文件不能碰，哪些模式必须沿用，哪些命令能验证结果。

第二，不要让 Hook 依赖交互式 shell。

比如你在终端里能用 node，不代表 Claude Code 的 Hook 里也能找到 node。如果你用 nvm，Hook 环境经常拿不到 PATH。

更稳的方式是写绝对路径，或者在 Hook 里显式设置 PATH：

export PATH="$HOME/.nvm/versions/node/v20.20.2/bin:$PATH"

第三，不要让模型做确定性转换。

格式化、lint、构建、测试、文件路径匹配，这些应该交给脚本。模型适合做判断、解释、归纳、生成草稿，不适合替代 deterministic tools。

第四，不要偷偷混用两套项目风格。

如果项目里同时有旧架构和新架构，必须显式告诉 AI 当前任务应该跟随哪一套。否则它很容易 blend，最后生成一段“看起来都像，但哪边都不对”的代码。

总结

claude-code-setup 的真正价值，不是让 Claude Code 多一个插件入口。

它提醒你把 AI coding 当成一套工程系统来设计：

• CLAUDE.md 负责项目级记忆和约束
• Skills 负责复用高频流程
• Hooks 负责即时验证和安全拦截
• MCP 负责接入外部事实
• Subagents 负责专业分工

裸用 Claude Code，很容易变成高级聊天窗口。

做好 setup 以后，它才开始接近一个受工程约束的 AI agent 工作环境。

真正会复利的不是下一个 framework。

而是：

• 一个 repo 一套规则
• 先读再写
• 每一步都验证
• 冲突显式暴露
• 失败 loudly fail
• 用脚本处理确定性问题
• 用 AI 处理判断和协作问题

这才是 AI coding 从“vibe-driven”走向“eval-driven”的分界线。

参考资料

• Claude Code Setup 插件页：https://claude.com/plugins/claude-code-setup
• Claude Code Plugins 文档：https://code.claude.com/docs/en/plugins
• Claude Code 插件安装与 marketplace 文档：
https://code.claude.com/docs/en/discover-plugins

2026.05.19 21:33 沪 · 赵巷

📌 声明：本文由 AI 辅助完成

claude-code-setup 实战：把 Claude Code 从聊天工具变成工程系统

先说清楚：它不是 claude-code setup