ENZOMEGA.
Clipping 微信公众号

别再-凭感觉-用 Claude Code 了：我把那个 5.4 万 Star 的最佳实践拆给你看

by Sam 原文 ↗
Created: 2026-05-26
#公众号文章

公众号名称：三木AI编程

作者名称：Sam

发布时间：2026-05-26 17:57

上周我在做一个出海的 SaaS 项目，让 Claude Code 加一个 /api/notifications 端点。

它给我生成了一个长这样的东西：路由风格跟我已有的 routes/users.py 完全对不上，命名一会儿驼峰一会儿下划线，测试文件零行,连 i18n 的中间件都没挂上。

我花了 40 分钟对齐规范,最后忍不住自己重写了。

​

为什么大多数人用 Claude Code 都在做无用功

我观察身边做出海 Web 的朋友,80% 的人用 Claude Code 的姿势是这样的:打开终端,敲一句 “帮我加个支付功能”,然后等结果。

结果当然是各种翻车。Stripe 的 webhook 验签忘了加,多语言的 key 全是硬编码,时区处理直接 new Date() 一把梭。

我自己也踩过这个坑。最离谱的一次,Claude 给我写的退款逻辑里,金额单位一会儿是分一会儿是元,上线前测试才发现,差点给用户多退 100 倍。

后来我才搞明白——这不是模型的问题,是没有把 Claude Code 当成工程系统来配置。

最近 GitHub 上有个项目叫 claude-code-best-practice,5.4 万 Star,2026 年 3 月趋势榜第三。作者是个巴基斯坦开发者,把 Claude Code 从”凭感觉用”到”工程化使用”的完整路径整理出来了。

我花了一个周末把它读完,又在自己的出海项目里实操了一遍。这篇文章就是我消化之后的版本——只讲对出海 Web 开发真正有用的部分。

​

核心心法:从 Vibe Coding 到 Agentic Engineering

先把这两个词翻译成人话。

Vibe Coding 就是凭感觉撸:每次对话都像跟一个失忆的实习生合作,他不知道你的项目架构,不记得你的代码规范,也不知道你昨天改了啥。

Agentic Engineering 是把 Claude 配置成你的工程系统:它知道你的技术栈(CLAUDE.md),遵循你的代码约定(Rules),按需加载专业知识(Skills),把复杂任务分发给专门的子代理(Agents),自动触发钩子(Hooks),还能直连外部工具(MCP)。

差距有多大?同样一句”帮我加个 notes 功能”:

​

  • Vibe 模式:随机生成 /api/notes,不遵循现有路由模式,没有测试,没有 i18n

  • Agentic 模式:严格按 routes/todos.py 的模式创建,自动集成进侧边栏,测试风格跟 test_todos.py 一致,多语言 key 自动加到 locales/ 下

说人话就是:前者是抽奖,后者是流水线。

​

六个核心模块,我只讲对出海项目最关键的四个

原 repo 列了六个模块(Commands、Agents、Skills、Hooks、MCP、Memory),全用一遍学习成本太高。我按出海 Web 开发的实际频率排了优先级,讲最值得先动手的四个。

第一步:用 CLAUDE.md 给项目装上”记忆”

这是性价比最高的一步,5 分钟见效。

在项目根目录创建 CLAUDE.md,把项目关键信息写进去。我自己出海项目的模板长这样:

# Project: NotionMate (出海笔记 SaaS)

## Tech Stack
- Frontend: Next.js 14 (App Router) + TypeScript + Tailwind
- Backend: FastAPI + PostgreSQL + Redis
- i18n: next-intl (支持 en/zh/ja/es/de)
- Payment: Stripe (subscription + one-time)
- Auth: Clerk
- Deploy: Vercel (frontend) + Fly.io (backend)

## Code Conventions
- API 路由: 复数名词 + RESTful (e.g., /api/notes, /api/users/:id/notes)
- 文件命名: kebab-case (note-editor.tsx, not NoteEditor.tsx)
- 时间处理: 后端统一存 UTC,前端用 dayjs + user timezone 转换
- 金额单位: 数据库存最小单位 (cents),展示层除以 100
- 错误处理: 自定义 AppError,前端用 toast 统一展示

## Critical Rules
- 禁止在代码里硬编码任何用户可见的文案,必须走 i18n
- Stripe webhook 必须验签,不能跳过
- 所有涉及金钱的接口必须写测试
- 数据库 migration 必须可回滚

说人话就是:你把项目的”为人处事原则”写下来,Claude 每次对话都会读这份文档。再也不用每次都念叨”记得用 dayjs 不要用 Date”。

大多数教程不告诉你的细节:CLAUDE.md 不要写超过 200 行,Claude 的注意力是有限的。把项目宪法写进去,具体的实现细节交给 Skills。我刚开始写了 800 行,结果 Claude 反而经常忽略前面的规则——注意力被稀释了。

第二步:用 Commands 把重复工作流固化

.claude/commands/ 目录下,每个 .md 文件就是一个命令。在 Claude Code 里输入 /命令名 就能触发。

我做出海项目最常用的一个命令是 /add-i18n-feature,文件长这样:

# /add-i18n-feature

When user asks to add a new feature, follow these steps:

1. Read existing similar feature in `app/[locale]/` to understand the pattern
2. Create the new page/component with all text using `useTranslations()` hook
3. Add translation keys to all 5 locale files: en.json, zh.json, ja.json, es.json, de.json
   - English: write the actual text
   - Other languages: use the format `[TODO-LOCALE] English text` so we can spot untranslated strings
4. Add a unit test following the pattern in `__tests__/`
5. Update the navigation in `components/sidebar.tsx` if it's a top-level page
6. Run `pnpm typecheck && pnpm test` and fix any errors
7. Show me a summary of files changed

Important: Never hardcode user-facing strings. If you're unsure about a string, ask me first.

这段配置在做什么:把”加一个支持多语言的功能”这件事的标准流程写死。以后我只要输入 /add-i18n-feature 加一个用户反馈页面,Claude 会按这 7 步走完。

这里有个细节要注意:第 3 步那个 [TODO-LOCALE] 前缀是我踩坑后加的——之前 Claude 直接把英文复制到所有语言文件里,上线后日本用户全看到英文,我两周后才发现。给未翻译内容打标记,远比”提醒 Claude 翻译”靠谱。

第三步:用 Agents 拆解复杂任务

Agents 在全新隔离上下文里运行。这点很关键——它意味着主对话的混乱不会污染 Agent 的判断。

我的出海项目里配了三个 Agent:

.claude/agents/
├── stripe-engineer.md    # 专门处理支付相关
├── i18n-translator.md    # 专门处理多语言翻译
└── seo-optimizer.md      # 专门处理出海 SEO

stripe-engineer.md 的核心配置:

# Stripe Engineer Agent

## Role
You are responsible for all Stripe-related code in this project.

## Tools (limited)
- Read, Write, Edit (only in /lib/stripe/, /app/api/stripe/, /app/api/webhooks/stripe/)
- Bash (only `pnpm test:stripe`)

## Pre-loaded Knowledge
- Skill: stripe-webhook-verification
- Skill: stripe-subscription-lifecycle
- Skill: stripe-tax-calculation (for EU VAT)

## Hard Rules
1. Every webhook handler MUST verify signature using STRIPE_WEBHOOK_SECRET
2. Every monetary value MUST be in cents (integer), never float
3. Every Stripe API call MUST be wrapped in try-catch with proper error logging
4. Test every change with `pnpm test:stripe` before declaring done

说人话就是:我让一个”只懂 Stripe 的专家”来处理支付,它的工具权限被限制在支付相关目录,知识库里预装了 Stripe 的踩坑经验。它不会去碰我的前端组件,也不会随便改数据库 schema。

反常识的点:很多人以为 Agent 越通用越好,其实越窄越强。我之前配过一个 “fullstack-engineer” 啥都能干,结果它在写支付代码时居然去改了 UI 样式。后来拆成三个专门 Agent,每个只干一件事,质量直接上一个台阶。

第四步:用 Hooks 兜住底线

Hooks 是在特定事件触发时自动运行的脚本,运行在 Claude 的 agentic loop 之外。

最有用的是 PreToolUse 钩子,在 Claude 调用工具(比如写文件、跑命令)之前先做一次校验。

我的 .claude/hooks/pre-tool-use.sh:

#!/bin/bash
# 这个钩子在 Claude 每次写文件前触发
# 防止它往敏感文件里塞代码

FILE_PATH="$1"

# 禁止修改 .env 和密钥文件
if [[ "$FILE_PATH" == *".env"* ]] || [[ "$FILE_PATH" == *"secrets"* ]]; then
echo"BLOCKED: Cannot modify $FILE_PATH"
exit 1
fi

# 禁止修改已部署的 migration 文件
if [[ "$FILE_PATH" == *"migrations/"* ]]; then
  LATEST=$(ls -t migrations/ | head -1)
if [[ "$FILE_PATH" != *"$LATEST"* ]]; then
    echo"BLOCKED: Cannot modify historical migration. Create a new one."
    exit 1
fi
fi

exit 0

这段代码在做什么:每次 Claude 想写文件,先经过这个守门员。碰 .env 直接拦,改老的 migration 直接拦。

这里有个细节要注意:Hooks 的退出码 exit 1 是真的能阻止 Claude 的操作的,不是给个 warning。我刚开始以为它只是日志,后来发现 Claude 真的会按报错信息调整行为,直接把”团队规范”硬编码进流程,比口头叮嘱可靠 100 倍。

​

我踩过的两个真实大坑

坑 1:Skills 加载顺序导致的”幻觉污染”

我有个 weather-fetcher skill 和一个 mock-data-generator skill。某次给 Agent 同时预加载这两个,结果 Agent 调用天气 API 时直接生成了假数据,完全没去请求真实接口。

怎么发现的:用户报 bug 说东京显示 25 度但实际下雨。我去查日志,发现根本没有 API 调用记录,瞬间冒冷汗。

怎么解决的:Skills 之间有”语义距离”概念。mock-data-generator 这种通用工具,不能跟具体业务 skill 一起加载——Claude 会”偷懒”,优先用 mock 数据。我把 mock 工具单独抽到 dev-only 的 Agent 里,生产 Agent 完全不接触它。

这个坑我卡了大概一个下午,排查到凌晨才找到根因。

坑 2:CLAUDE.md 写得太”人性化”被忽略

最开始我的 CLAUDE.md 写得很文艺:“我们这个项目追求优雅简洁,代码应该像诗一样……”

结果 Claude 完全不鸟这些抒情段落,生成的代码该乱还是乱。

怎么发现的:连续三次让它加功能,代码风格都跟现有项目不一致,我才意识到是 CLAUDE.md 出了问题。

怎么解决的:把所有”软规则”删掉,只留可验证的硬规则。比如不写”代码要简洁”,改写”单个函数不超过 50 行”;不写”注意性能”,改写”列表渲染必须用 React.memo + useMemo”。

说人话就是:Claude 读 CLAUDE.md 的方式更像在读 ESLint 配置,不是在读散文。能被自动化检查的规则,才是有效规则。

​

总结

如果只让我留一句话给还在凭感觉用 Claude Code 的人,我会说:

​

Claude Code 不是一个聊天框,是一个需要你认真配置的工程系统。配置一次,受益半年。

那个 5.4 万 Star 的 repo 之所以火,不是因为技巧多稀奇,而是它把”散乱的个人经验”变成了”可复制的工程模板”。这件事,值得你花一个周末认真做一遍。

最后一个实际的问题： 如果你已经在用 Claude Code 做出海项目,我很好奇:你的 CLAUDE.md 里写的第一条硬规则是什么?为什么是这一条?

来评论区聊聊,我赌一包辣条——头三条规则,基本能看出一个团队的工程素养在哪个层级。

cover_image

Original Sam 三木AI编程

内容效果不满意？点此反馈

输入关键词开始搜索