AI 辅助编程的开发者，大概率都踩过这样的坑：模型凭空写代码、不符合项目规范、乱改存量逻辑、反复沟通对齐需求，明明AI工具在手，编码效率反而被无效拉扯拖慢。

       其实多数时候，不是模型不够好用，而是你少了一份核心兜底配置文件。

       很多人忽略的 CLAUDE.md，正是适配 Claude Code 全项目场景的专属核心上下文文件，也是打通AI与本地代码库、业务开发需求的关键桥梁。

       简单来说，它的核心作用，就是给 AI 立好专属「项目规矩」、划清开发边界、同步全量项目核心信息。

       不用反复手动叮嘱开发规范，不用一次次修正适配逻辑，提前把所有项目要求、技术栈规则、代码风格标准、存量业务逻辑要点写进 CLAUDE.md，后续所有 AI 编码动作，都会自动对标落地。

这里要划一个关键重点：

       只要你在当前项目中调用 Claude AI 执行代码新增、存量代码优化、逻辑迭代修改、Bug 定向修复等任意操作，模型都会优先读取、优先对标 CLAUDE.md 中的全部规则要求。

       这份文件，相当于整个项目的「AI 开发专属说明书」，也是我们降本提效、规避 AI 乱写乱改问题的最优解。

       写得标准、贴合项目实况的 CLAUDE.md，能直接帮你省去一半以上的调试、返工、重复对齐沟通成本，全程轻量化托管 AI 全流程编码工作。

       但现实情况是：绝大多数开发者要么不会搭建合规规范的 CLAUDE.md，要么随便敷衍写两行基础信息，完全发挥不出这份核心文件的真正作用。

别盲目踩坑、别无效试错。

       今天这篇干货长文，不讲废话、不绕弯路，一次性把 CLAUDE.md 相关必备核心知识点、标准化搭建逻辑、落地实操技巧、全场景适配要点全部拆解清楚。

       从零手把手带你搭建一份适配自身业务、贴合代码库实况、直接落地可用的高品质 CLAUDE.md，全程优化 AI 协作编码链路，把繁琐编码流程做简、做顺、做高效。

一、先抓基础：CLAUDE.md 标准存放位置+合规格式，零出错打底

       想要CLAUDE.md生效不失效，第一步就别栽在基础配置上，位置放错、格式乱套，后续所有规则全都会失效，AI全程无法精准读取适配。

✅ 固定存放路径

       CLAUDE.md 无需嵌套分装、不用归类归档，统一直接放在项目仓库根目录即可，和package.json、.env等核心配置文件同级摆放，适配所有前端、全栈、后端各类开发项目，通用性拉满。

       举个实操场景：如果你正在搭建 React、Next.js 主流网页应用，直接把文件丢入项目首层目录，无需额外新建文件夹归集， Claude Code 启动对话后会自动全域检索、优先加载识别，不用手动额外配置挂载路径。

✅ 统一标准格式

       全程采用通用轻量化Markdown 格式编写，后缀固定为 .md，适配代码仓库原生解析规则、适配编辑器全品类插件、适配Claude全系列模型读取逻辑，不用切换复杂排版语法，上手零门槛，纯文本编辑就能快速写完。

## Project Overview
Short explanation of what the project is.
## Tech Stack
- TypeScript
- Next.js
- Tailwind
- ShadCN
## Architecture
Explain folders and patterns.
## Coding Rules
- Use functional React components
- Prefer server components
- Use Tailwind utilities instead of custom CSS
## Design System
- Follow ShadCN patterns
- Use tokens from /styles/tokens.ts
## Commands
npm run dev
npm run build

       这里补充官方关键底层逻辑：Anthropic 官方明确标注，CLAUDE.md 是 Claude Code 专属项目长效记忆载体，每一次新建AI编码对话、每一轮迭代交互，系统都会前置自动加载全文内容。它不会生硬强制锁死代码逻辑，而是作为全域核心上下文，全程锚定AI的编码思路、改写尺度、风格标准，柔性规范全量开发动作。

二、不用盲目瞎写：10大通用核心板块，全覆盖适配99%业务项目

       没有万能通用的CLAUDE.md模板，不用照搬小众非标格式，但行业通用刚需核心板块高度统一。下面拆解10个必写标准化模块，按需微调贴合自身业务，就能直接落地复用，适配私有业务、通用开源、政企合规各类项目场景。

1、项目概述：给AI搭好清晰业务心智底座（优先级TOP1）

      这是全文含金量最高的核心板块，直接决定AI能不能读懂你的项目底色、不跑偏开发方向。不用堆砌空话、不用铺垫品牌背景，只用直白简洁语言，说清4个核心关键信息就行。

✅ 必写核心要点：产品核心定位、目标使用人群、核心迭代优化方向、硬性业务约束/UX体验红线；全程控制在3-5小段，精简干练最佳。

❌ 千万别写：冗长品牌溯源故事、空泛价值口号、和代码落地无关的营销话术，只会干扰AI判断、稀释核心规则权重。

✅ 标准优质示范：

## Project Overview
This project is a web app for product designers to generate 
and refine landing pages with AI.
Primary users are startup founders and marketers who want
high-quality output fast.
The product optimizes for:
- visual polish
- speed of iteration
- clean responsive code
- easy handoff to engineering
Avoid over-engineering. Prefer clarity over cleverness.

项目概述

      本项目为面向全域产品设计师的AI赋能落地页极速生成Web应用。核心服务人群为初创团队创始人、全域营销运营从业者，核心诉求是快速产出高品质可视化页面、缩短落地迭代周期。

      产品核心优化优先级：页面视觉质感优先、迭代响应速度为辅、合规轻量化响应式代码兜底、无缝对接研发团队工程化交付链路。全程拒绝过度工程化冗余开发，优先保障代码可读性与落地实用性。

💡 实操小贴士：写完自查一句，能不能让AI精准答出「这是什么产品、开发核心侧重是什么」，能答合格，答不出直接重写。

2、全量技术栈：杜绝AI乱引依赖、错配框架版本

很多开发者踩坑：AI自主引入冷门库、兼容版本不匹配、和项目现有技术体系冲突，全是没写清技术栈导致的无效返工。这一板块直接规避所有兼容适配隐患。

✅ 必写核心要点：精准列明框架版本、编程语言、全局样式方案、全局组件库、状态管理工具、单元测试工具、构建打包工具、后端/数据链路配套设施。

核心原则：拒绝模糊笼统表述，拒绝简写笼统标签，同时明确标注禁止使用的技术、废弃依赖、淘汰组件，双向兜底规避出错。

✅ 标准优质示范：​​​​​​​

## Tech Stack
- Next.js 15 with App Router
- TypeScript
- Tailwind CSS
- shadcn/ui
- React Hook Form + Zod for forms
- Supabase for auth and data
- Vitest for unit tests
Do not introduce:
- Redux
- styled-components
- Material UI
unless explicitly requested.

全域技术栈规范

• 核心框架：Next.js 15 全量启用App Router架构
• 开发语言：严格全域TypeScript强类型校验
• 样式方案：原生Tailwind CSS全局统一样式
• 基础组件：shadcn/ui官方原生组件库
• 表单能力：React Hook Form + Zod联动校验
• 权限数据：Supabase统一托管认证与业务数据
• 单元测试：Vitest全域轻量化测试

🚫 严格禁止引入：Redux全局状态库、styled-components自定义样式、Material UI非标组件，无专项书面审批一律不准新增。

3、项目架构&目录权责：教会AI读懂仓库分工逻辑

核心作用：规范代码存放位置、统一分层开发逻辑、杜绝仓库杂乱冗余、避免核心目录乱改动，从源头规避项目架构崩坏。

✅ 必写核心要点：核心一级目录职能拆解、分层业务权责边界、全局数据流转链路、关注点分离标准、新增业务代码固定投放目录。重点写决策规则，不只是单纯罗列文件夹名称。

✅ 标准优质示范：​​​​​​​

## Architecture
- `app/` contains routes and server components
- `components/ui/` contains reusable design-system components
- `components/marketing/` contains landing-page sections
- `lib/` contains utilities, API helpers, and shared config
- `features/` contains feature-specific business logic
- `types/` contains shared TypeScript types
Rules:
- Keep page-level composition in route files
- Move repeated UI into reusable components
- Keep side effects out of UI components when possible
- Prefer server-side data fetching unless client interactivity is required

全局架构&目录权责规范

• /app：全域路由统一管控、服务端组件专属挂载目录
• /components/ui：复用型通用设计原子组件，全域共享调用
• /components/marketing：营销落地页专属区块、宣传可视化模块
• /lib：全局工具函数、接口请求封装、公共基础配置项
• /features：垂直专属业务线UI页面+闭环业务逻辑
• /types：全域通用TS类型定义、接口规范兜底

🔒 硬性架构规则：页面级组合逻辑统一放在路由文件、重复UI全域抽离复用组件、UI组件禁止嵌套冗余副作用、无客户端交互场景优先服务端拉取数据。

💡 实操小贴士：额外加一句「新增业务资源统一投放目录」，后续迭代扩容、重构优化，AI全程自动对标不乱放。

⚠️ 高频安全重点提醒：项目对接第三方付费接口、全域工具类接口，所有API密钥、私密凭证，统一加密存入根目录.env文件，绝对禁止硬编码写入业务代码。同时在CLAUDE.md中标注：「全局接口密钥统一托管于根目录.env」，规避密钥泄露、线上安全风控事故。

4、编码硬性公约：直接拉高AI输出代码原生质量

除项目概述外，这是第二核心刚需板块，直接决定产出代码是否规范可读、是否便于团队协同、是否无需二次重构优化。所有日常编码细节，全部明文落地规则。

✅ 必写核心要点：全局文件命名规范、组件编写固定范式、TS强类型约束标准、单文件行数上限、模块化导入导出规则、全局异常捕获机制、注释留白规范、异步请求统一写法。

核心原则：只写可落地、可校验、可强制执行的具象规则，不写「代码写干净、逻辑写规范」这类空话。

✅ 标准优质示范：​​​​​​​

## Coding Conventions
- Use TypeScript strictly; avoid `any`
- Prefer functional components
- Prefer named exports for shared modules
- Use async/await instead of chained promises
- Keep components focused and composable
- Extract repeated logic into hooks or helpers
- Prefer descriptive variable names over abbreviations
- Add comments only when intent is non-obvious
- Do not leave dead code or commented-out blocks

全域编码强制公约

• 全域强制执行TypeScript，严令禁止滥用any兜底类型，优先自动推导类型或手动定义标准Interface
• 前端组件统一采用函数式写法，淘汰老旧类组件，全域对齐轻量化开发范式
• 通用业务模块统一命名导出，路由专属文件可按需默认导出
• 异步全链路统一使用async/await语法，禁止链式嵌套Promise回调地狱
• 单业务组件严控200行以内，超出行数必须拆分子组件、抽离通用逻辑
• 重复高频业务逻辑统一抽离通用Hooks或公共工具函数
• 变量语义化直白命名，拒绝小众缩写、模糊简写，降低团队解读成本
• 仅复杂核心业务逻辑补充注释，常规清晰直白代码禁止冗余注释
• 全域禁止留存无效死代码、注释冗余代码，完工即时清理净化

5、UI视觉&设计系统：前端项目提效核心利器

      所有前端可视化项目，这一板块性价比直接拉满，一次性对齐全局视觉标准，后续AI写页面、改样式、调布局，全程零视觉偏差、零风格割裂。

✅ 必写核心要点：全局视觉基调、统一间距规范、全局排版标准、交互反馈范式、多端响应式适配规则、无障碍访问兼容要求、组件复用搭配禁忌。

✅ 标准优质示范：​​​​​​​

## UI and Design Rules
- Use shadcn/ui primitives as the default foundation
- Prefer spacious layouts and strong visual hierarchy
- Use restrained color usage; rely on typography, spacing, and contrast
- Prefer 8px spacing rhythm
- Buttons should have clear primary/secondary hierarchy
- Forms should be short, scannable, and mobile-friendly
- Every interactive element must have visible hover, focus, and disabled states
- Meet accessibility expectations for contrast, labels, and keyboard navigation

UI视觉&设计全域规范

• 底层视觉原子统一复用shadcn/ui原生基础组件，不自定义重构基础样式
• 页面布局优先宽松留白排版，强化层级视觉动线，提升浏览舒适度
• 色彩克制轻量化搭配，靠排版、间距、明暗对比打造视觉层级，不滥用高饱和色彩
• 全域间距统一遵循8px基础网格节奏，全局规整统一，无杂乱非标间距
• 按钮强制区分主按钮/次按钮/弱按钮层级，交互权责清晰不混淆
• 表单轻量化极简设计，适配移动端全屏浏览，排版紧凑不冗余
• 所有可交互元素必备hover、聚焦、禁用三类状态反馈，无视觉空白盲区、全域严格合规无障碍对比度、标签语义化、键盘全链路导航适配

6、文案语气规范：落地页/运营产品项目必填

容易被忽略，但对ToC产品、营销落地页、后台运营面板至关重要，避免AI产出浮夸营销话术、晦涩技术黑话，全程贴合产品官方品牌调性。

✅ 必写核心要点：文案简洁度偏好、行文直白程度、语气专业调性、句式长短标准、禁用营销话术清单。可直接附上内部品牌文案规范链接，一键对齐标准。

✅ 标准优质示范：​​​​​​​

## Content Guidelines
- Use concise, confident language
- Avoid hype and empty marketing phrases
- Headlines should be clear before clever
- Body copy should focus on user outcomes
- Prefer short paragraphs and scannable structure
- Avoid jargon unless the audience clearly expects it

7、测试验收&质量红线：避免AI浅开发、低质量交付

提前划定项目完工验收标准，防止AI只写功能不做校验、漏测边界场景、少写单元用例，交付后批量爆Bug，省下全量回归调试时间。

✅ 必写核心要点：必测业务场景、新增代码强制配套用例、Lint语法校验要求、类型强检标准、任务真正完工的判定条件。

✅ 标准优质示范：​​​​​​​

## Testing and Quality
Before considering a task complete:
- run typecheck
- run lint
- run relevant tests for modified logic
Testing rules:
- add unit tests for reusable logic
- do not add heavy test scaffolding for simple presentational sections
- ensure responsive behavior for UI changes
- verify empty, loading, and error states where relevant

8、文件组件投放规则：严防仓库冗余杂乱、重复造轮子

中大型长效刚需板块，专治项目迭代越更越乱、重复组件泛滥、目录权责模糊问题，长效维护项目必备，守住仓库整洁底线。

✅ 必写核心要点：新增文件专属投放目录、存量组件修改判定标准、何时抽离通用抽象能力、全域统一命名范式。

✅ 标准优质示范：​​​​​​​

## File Placement Rules
- Add new landing-page sections to `components/marketing/sections`
- Add reusable primitives to `components/ui`
- Put shared helpers in `lib`
- Do not create a new abstraction for one-off usage
- Prefer editing existing components over creating near-duplicates

9、安全可控变更规则：守住核心业务架构底线

真实线上生产项目刚需核心，明确告知AI：哪些核心路由、底层架构、权限链路绝对不能随意改动，规避高风险误操作，杜绝天价重构返工成本。

✅ 必写核心要点：禁止擅自更名公共API路由、禁止私自改动数据库底层表结构、严禁篡改核心权限登录链路、迭代必须兼容历史存量版本、架构重大调整提前标注报备。

✅ 标准优质示范：​​​​​​​

## Safety Rules
- Do not rename public API routes unless explicitly requested
- Do not change database schema without calling it out clearly
- Do not modify auth flows unless the task requires it
- Preserve backward compatibility for shared components
- Flag major architectural changes before implementing them

10、项目专属快捷指令：AI直接上手干活，不用反复问询

      贴合Anthropic官方适配要求，把本地常用开发、启动、打包、校验、测试全量真实命令写入文件，AI可直接自主调用执行，不用手动输入指令、反复对齐问询。

✅ 标准示范：​​​​​​​

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Build: `pnpm build`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`
- Test: `pnpm test`

项目专属快捷运维指令

• 项目依赖安装：pnpm install
• 本地研发启动：pnpm dev
• 线上打包构建：pnpm build
• 代码语法校验：pnpm lint
• 全域类型强检：pnpm typecheck
• 自动化单元测试：pnpm test

三、登录页面的CLAUDE.md文件实例