## Tech Stack- Next.js 15 App Router + TypeScript- Tailwind CSS + shadcn/ui- Supabase Auth + PostgreSQL- Zustand for small client-side stores## Do NOT Introduce Unless Explicitly Requested- Redux: project already migrated to Zustand + React Context.- styled-components: use Tailwind utilities and existing design tokens.- Material UI: conflicts with shadcn/ui visual system.- MongoDB: data layer is PostgreSQL.- Moment.js: use date-fns already installed.- New auth provider: auth flow is locked behind review.
这段通常比“请写优雅代码”更有用。
因为它能挡住后续一串隐性成本：
text
新依赖样式冲突包体积变大测试变多团队认知分裂后续会话继续沿用错误选择
如果团队通过 4SAPI 接入不同模型，还可以把这件事再往前收一层：
markdown
## Model PolicyDefault coding model is configured through 4SAPI.Do not ask users to paste raw provider keys into project files.Do not hardcode model names in application code unless the file already does so.Read model routing config from env or the existing config layer.
这几行能避免 Claude 把某个供应商的 Key、模型名或 base URL 写死进代码里。
3. 规则必须能被检查，不要写成口号
CLAUDE.md 里最常见的废话是：
markdown
- Write clean code.- Keep it simple.- Be performant.- Follow best practices.
这些话都对。
但没用。
因为 Claude 没法稳定判断“clean”到底是什么。你也没法在 review 时快速判定它有没有遵守。
好的规则应该能被检查。
差的写法：
markdown
## Coding Rules- 写干净的代码- 保持简洁- 注意性能- 不要过度设计
好的写法：
markdown
## Coding Rules- Use named exports by default, except framework-required files.- Avoid `any`; use interfaces, generics, or `unknown` with narrowing.- Keep React components under 200 lines unless there is a clear reason.- Use async/await instead of `.then()` chains.- Prefer existing helpers in `src/lib/` before creating new utilities.- Do not leave commented-out code, debug logs, or temporary TODOs.- Add tests for bug fixes that change behavior.
测试方法很简单：
text
读完规则后，你能不能在 5 秒内判断一段代码是否违反？
能，就是好规则。
不能，就继续改。
再举几个更适合工程项目的规则：
markdown
## API Rules- Route handlers must validate input with the existing schema helpers.- Never return raw database errors to clients.- All external API calls must have timeout and retry policy.- New endpoints must include success and failure tests.
markdown
## UI Rules- Use components from `src/components/ui/` before building custom controls.- Buttons must use existing variants from `button.tsx`.- Do not introduce new colors outside Tailwind theme tokens.- Loading, empty, error, and success states are required for async views.
这才是 Claude Code 能执行的规则。
4. CLAUDE.md 要做路由器，不要做图书馆
很多人会把完整架构文档塞进 CLAUDE.md。
比如：
text
系统架构 800 行数据库设计 500 行部署流程 300 行接口说明 1000 行
最后根文件变成一本书。
Claude 每次进项目都要先背书，哪怕你只是让它改一个按钮文案。
更好的做法是把 CLAUDE.md 当路由器：
markdown
## Project Documents- Architecture overview: `docs/architecture.md`- API contract: `docs/api.md`- Data model notes: `docs/data-model.md`- Deployment runbook: `docs/deploy.md`- ADRs: `docs/adrs/`- Archived decisions: `docs/archive/` (ignore unless explicitly requested)
Claude 不需要每次都读完整架构。
它只需要知道：
text
需要架构时，去 docs/architecture.md。需要 API 合同时，去 docs/api.md。需要历史决策时，去 docs/adrs/。旧资料在 archive，没要求别碰。
这就是渐进式上下文。
可以在 CLAUDE.md 里写得更明确：
markdown
## Context Loading PolicyAlways load:- `CLAUDE.md`- Files directly related to the task.Load on demand:- `docs/architecture.md` for cross-module changes.- `docs/api.md` for endpoint or contract changes.- `docs/adrs/` when changing a documented decision.Do not load unless requested:- `docs/archive/`- old migration notes- product brainstorm documents
这一招能明显省上下文，也能减少 Claude 被历史材料带偏。
对接 4SAPI 时也一样。
不要在 CLAUDE.md 里写一长串模型价格表和供应商说明。只放路由入口：
markdown
## Model GatewayModel routing and keys are managed outside this repository.Read local examples from:- `docs/model-routing.md`- `.env.example`Never commit real API keys.Never paste provider secrets into documentation.
真正的成本规则、模型分组、Key 策略，可以放到单独文档。CLAUDE.md 只告诉 Claude 去哪里看。
Claude Code 支持在子目录放 CLAUDE.md。当它处理对应目录里的文件时，会按需加载本地规则。
这很适合给危险区域装护栏。
比如认证目录：
markdown
# src/auth/CLAUDE.md## Security Rules- Do not change token validation logic unless explicitly requested.- Do not introduce a new auth provider without updating tests and docs.- Do not log tokens, sessions, cookies, or auth headers.- All auth changes must pass `pnpm test src/auth`.## Known Traps- Magic link IDs use `crypto.randomUUID()`. Do not replace with Math.random().- Sessions are stored in Redis, not process memory.- Middleware must preserve existing redirect behavior.## Review RequirementFor auth changes, summarize:1. What security behavior changed.2. Which tests cover it.3. What remains risky.
再比如账单目录：
markdown
# src/billing/CLAUDE.md## Billing Rules- Never change invoice totals without adding tests.- Currency values are stored in cents.- Do not use floating point arithmetic for money.- Webhook handlers must be idempotent.- Any provider signature verification change requires review.
如果你的项目里有 4SAPI 或其他模型中转层，也建议给对应目录单独放一份：
markdown
# src/model-gateway/CLAUDE.md## Gateway Rules- Never hardcode provider API keys.- Never bypass the existing rate-limit middleware.- Preserve request/response logging redaction.- Do not expose raw provider error bodies to clients.- New model routes must include timeout, retry, and cost tagging.## Required Checks- Run gateway unit tests after changes.- Manually inspect redaction for logs touching `Authorization`, `api_key`, or `token`.
这种本地 CLAUDE.md 的好处是精准。
你不需要让 Claude 每次改按钮都读一堆账单规则，但它一旦进入账单目录，就必须知道这里不能乱动。
6. 重要规则别只写在 CLAUDE.md，要变成 hooks
CLAUDE.md 是提醒。
Hooks 才是门禁。
Claude Code 的 hooks 机制允许你在工具调用前后执行脚本。官方文档也明确提醒，hooks 会自动执行，所以要谨慎编写，并把安全性当成自己的责任。
适合写进 CLAUDE.md 的规则：
text
倾向、偏好、协作方式、代码风格、项目说明。
适合变成 hook 的规则：
text
格式化测试禁止改敏感文件禁止提交密钥检查 lint校验生成文件
可以在 CLAUDE.md 里这样写：
markdown
## Hooks & Quality GatesThe rules below are enforced by hooks, not just reminders:- Format edited files after code changes.- Run related tests after modifying core modules.- Block edits to `src/auth/`, `src/billing/`, and `prisma/migrations/` unless confirmed.- Scan for secrets before final summary.If a hook fails, explain the failure and do not claim the task is complete.
注意：上面是演示思路，实际变量名和可用上下文要按你当前 Claude Code 版本的 hooks 文档来写。
不要为了“看起来自动化”乱配 hook。
尤其不要让 hook 直接做这些事：
text
删除文件自动提交自动推送自动改数据库自动旋转生产 Key自动执行远程脚本
我更推荐先从三类低风险 hook 开始：
Hook
作用
格式化
避免每次都提醒缩进、换行、排序
相关测试
防止 Claude 改完不验证
密钥扫描
防止误把 Key 写入文件
这和 4SAPI 的治理逻辑是一致的。
能用规则自动挡住的，就不要靠人反复提醒。能由中转站限制的模型调用，也不要靠每个工程师自觉省钱。
7. 用 MEMORY.md 留下跨会话经验，但别让它失控
Claude Code 有多种记忆位置。项目级 CLAUDE.md 是最常见的入口。
但还有一种简单粗暴的方法：在项目里维护一个 MEMORY.md，专门记录“上次踩过的坑”。
你可以在 CLAUDE.md 里写：
markdown
## Project MemoryBefore starting non-trivial tasks, read `MEMORY.md` if it exists.Use `MEMORY.md` for:- recurring bugs- important implementation discoveries- local setup quirks- known flaky tests- decisions made during previous tasksDo not store:- secrets- credentials- personal data- temporary notes older than 30 daysAt the end of a task, suggest updates to `MEMORY.md` only when the discovery is likely to matter again.
这比很多复杂“长期记忆”方案更容易落地。
优点很实际：
text
能进 Git能 review能删除能追溯不用额外数据库不会黑箱召回
但它也有风险。
MEMORY.md 很容易变成新的垃圾桶。
所以要加一条清理规则：
markdown
## Memory HygieneKeep `MEMORY.md` under 100 lines.Prefer bullets with date and owner.Remove stale notes when they no longer affect future work.
示例：
markdown
# MEMORY.md- 2026-06-17: `pnpm test` is slow on Windows; use `pnpm vitest src/auth` for auth-only checks.- 2026-06-17: Billing amounts are cents; never use floats for invoice math.- 2026-06-17: 4SAPI model route tests require `MODEL_GATEWAY_TEST_MODE=mock`.
它记录的不是“项目所有知识”，而是未来任务最可能再次用到的 5%。
8. 把你的协作风格写进去，省掉每次开场白
很多人每次开新会话，都会先说一堆：
text
先别急着改。先读代码。不确定就问我。回复用中文。不要讲废话。改完跑测试。路径写清楚。
这些完全可以放进 CLAUDE.md。
比如：
markdown
## Working Style- Read relevant files before proposing changes.- For risky changes, propose a short plan first.- For small obvious fixes, implement directly.- Ask when requirements are ambiguous and a wrong assumption is costly.- Do not start replies with “Great question” or generic encouragement.- Reply in Chinese. Keep code comments in English.- Use absolute file paths when referencing files.- Final response must include changed files and verification results.
这几行能省掉很多沟通成本。
但注意，不要把协作风格写成情绪宣泄。
差的写法：
markdown
- 不要写垃圾代码。- 不要自作聪明。- 不要浪费我时间。
好的写法：
markdown
- Do not introduce abstractions unless they remove duplicated logic or match an existing pattern.- If you are unsure about a behavior, inspect existing tests before guessing.- Do not refactor unrelated files while fixing a bug.
AI 不怕规则严。
AI 怕规则含糊。
一张表总结
经验
错误做法
推荐做法
控制长度
写成项目百科
根文件压到 200 行以内
禁止清单
只写当前技术栈
写清楚不要引入哪些库
可检查规则
写“干净、简洁、高性能”
写成可判断的工程规则
文档路由
把所有文档塞进来
只放文档入口和加载策略
本地规则
一个根文件管全项目
高风险目录放本地 CLAUDE.md
Hooks
靠 Claude 记得跑测试
用 hooks 做格式化、测试、密钥扫描
长期记忆
每次会话重新解释
用 MEMORY.md 留下可 review 的经验
协作风格
每次开场重复说
写进 Working Style
可以直接复制的一版最小 CLAUDE.md
如果你现在还没有 CLAUDE.md，可以先用这版。
markdown
# CLAUDE.md## Project OverviewThis is a B2B analytics dashboard for operations managers.Priority: correctness > loading speed > UX richness > visual polish.## Tech Stack- Next.js 15 App Router + TypeScript- Tailwind CSS + shadcn/ui- Supabase Auth + PostgreSQL- Vitest for unit tests## Do NOT Introduce Unless Explicitly Requested- Redux- styled-components- Material UI- MongoDB- Real API keys or provider secrets in code/docs## Coding Rules- Use named exports by default, except framework-required files.- Avoid `any`; use interfaces, generics, or `unknown` with narrowing.- Prefer existing helpers before creating new utilities.- Do not leave commented-out code or debug logs.- Add tests for behavior changes.## Context Loading Policy- Read files directly related to the task before editing.- Load `docs/architecture.md` for cross-module changes.- Load `docs/api.md` for endpoint or contract changes.- Ignore `docs/archive/` unless explicitly requested.## Sensitive Areas- `src/auth/`: read local CLAUDE.md before edits.- `src/billing/`: read local CLAUDE.md before edits.- `prisma/migrations/`: do not edit without confirmation.- `src/model-gateway/`: never hardcode provider keys or bypass rate limits.## Quality Gates- Run related tests after behavior changes.- If tests cannot run, explain why.- If hooks fail, do not claim completion.## Project Memory- Read `MEMORY.md` before non-trivial tasks if it exists.- Suggest updates only for discoveries likely to matter again.- Never store secrets or personal data in memory files.## Working Style- For risky changes, propose a short plan first.- For small obvious fixes, implement directly.- Ask when ambiguity is costly.- Reply in Chinese. Keep code comments in English.- Final response must include changed files and verification results.
这版不完美，但方向是对的：短、具体、可检查、能路由、知道红线。
现在就能做的 5 件事
打开你的项目，按这个顺序改：
text
1. 把根目录 CLAUDE.md 删到 200 行以内。2. 加一个 Do NOT Introduce 区块，至少列 5 个禁用项。3. 把“干净、简洁、最佳实践”改成可检查规则。4. 给 auth、billing、infra、model-gateway 这类高风险目录加本地 CLAUDE.md。5. 把格式化、测试、密钥扫描做成 hooks 或现有 CI 门禁。
