写了一个 claude.md，AI 写代码终于不乱来了

claude.md 是什么？

最近在使用 Claude Code、MCP、Agent 自动化开发时，你大概率会看到一个文件：claude.md。

它长得像 README，但不是给人看的；

它又像 Prompt，但不是一次性的。

很多人会困惑：

👉 claude.md 到底该写什么？

👉 有没有规范？

👉 写了真的有用吗？

本文结合真实工程实践，总结一套 可落地、可复制的 claude.md 设计方法，目标只有一个：

让 AI 真正"懂你的项目"，并且不乱来。

一、claude.md 到底解决什么问题？

一句话：

claude.md 是给 AI Agent 阅读的项目工程规范文件。

你可以把它理解为：

面向对象	文档
给人看的项目说明	README.md
给 AI 的工程规则	claude.md

Claude 在执行任务时会自动读取它，用来：

理解项目目标和边界
识别真实技术栈（避免乱猜版本）
理解目录结构，避免写错路径
遵守编码和架构约束
正确使用 MCP 工具
避免破坏性修改

如果项目没有 claude.md，AI 常见翻车包括：

Vue2 项目被写成 Vue3
路径写错，文件生成在奇怪目录
引入根本不需要的依赖
不经确认大范围重构
抓网页不用 MCP，开始"编造内容"

这些问题本质不是模型能力问题，而是：

缺乏稳定、可持续的工程约束输入。

二、有没有官方规范？

目前 Anthropic 并没有发布强制规范。

但社区已经形成一些事实标准：

✅ 文件名固定：claude.md
✅ 放在项目根目录
✅ 使用 Markdown
✅ 内容偏工程约束，而不是宣传文案

目标很明确：

降低不确定性，提高工程可控性。

三、推荐的标准结构

在多个项目实践中，一个成熟的 claude.md 通常包含 6 个模块：

markdown 复制代码

1. Project Overview
2. Environment / Stack
3. Directory Structure
4. Development Rules
5. Tooling / MCP Usage
6. Output Expectations

下面逐一拆解。

四、模块设计详解

1️⃣ Project Overview：告诉 AI 你在干什么

这一部分要回答三个问题：

项目是做什么的？
核心目标是什么？
Claude 的角色是什么？

示例：

vbnet 复制代码

# Project Overview

This project is a visual template editor built with Vue2 and GrapesJS.
The goal is to allow users to design templates and export HTML.

Claude should:
- Help implement features
- Fix bugs
- Avoid breaking existing behavior

注意重点：

❌ 不要写宣传文案

✅ 要写可执行约束

2️⃣ Environment / Stack：防止 AI 猜错技术栈

这是降低错误率最有效的一段。

markdown 复制代码

# Environment

- Frontend: Vue 2.x
- Editor: GrapesJS
- Backend: Flask
- Node: >= 18
- Package Manager: pnpm

否则 AI 很容易：

默认 Vue3
默认最新库 API
默认 npm
默认 Node 最新特性

3️⃣ Directory Structure：防止路径事故

明确真实目录结构：

bash 复制代码

# Directory Structure

src/
  components/
  plugins/
server/
  app.py

对自动生成代码、批量修改文件非常关键。

4️⃣ Development Rules：claude.md 的灵魂

这是最重要的一部分。

你可以约束：

禁止使用的 API
架构原则
安全规则
性能底线
风格约定

示例：

markdown 复制代码

# Development Rules

- Do NOT use Vue 3 APIs (no ref, reactive, setup).
- Prefer simple functions over heavy abstractions.
- Avoid introducing new dependencies.
- Do not change existing APIs unless explicitly asked.

好的规则具备三个特征：

✔️ 明确

✔️ 可验证

✔️ 可执行

5️⃣ Tooling / MCP Usage：避免工具滥用

如果你在使用 MCP，一定要写清楚工具规则：

markdown 复制代码

# Tooling

Available tools:
- mcp-fetch
- filesystem
- git

Rules:
- Always use mcp-fetch to fetch web content.
- Ask before modifying more than 3 files.

否则 AI 很容易：

模拟浏览器抓网页（失败）
跳过工具直接编造内容
不经确认修改大量文件

6️⃣ Output Expectations：稳定输出质量

规范输出格式和语言：

markdown 复制代码

# Output Expectations

- Respond in Chinese.
- Provide complete runnable code.
- Show diffs when modifying files.

这能显著减少沟通成本。

五、一个可直接使用的完整模板

markdown 复制代码

# Project Overview

This project is a visual editor built with Vue2 and GrapesJS.

Claude should assist with:
- Feature development
- Bug fixing
- Refactoring

# Environment

- Frontend: Vue 2.x
- Backend: Flask
- Package Manager: pnpm

# Directory Structure

src/
  components/
  plugins/
server/
  app.py

# Development Rules

- Do NOT use Vue 3 APIs.
- Avoid unnecessary dependencies.
- Keep backward compatibility.
- Prefer readable code.

# Tooling / MCP

Available tools:
- mcp-fetch
- filesystem
- git

Rules:
- Use mcp-fetch for web fetching.
- Ask before modifying multiple files.

# Output Expectations

- Respond in Chinese.
- Provide complete code blocks.

复制即可用。

六、进阶玩法：把 AI 真正纳入工程体系

当你开始把 AI 当"工程成员"而不是"聊天工具"，claude.md 会越来越重要。

几个可进阶方向：

✅ 多角色约束

php 复制代码

If acting as Reviewer:
- Only review code, do not modify.

If acting as Implementer:
- Always include tests.

✅ 自动化规范

sql 复制代码

Git commit format:
feat(scope): description
fix(scope): description

✅ 安全与性能底线

diff 复制代码

- Never log tokens or secrets.
- Avoid synchronous IO in backend.

七、总结

claude.md 的价值，不是"写给 AI 看说明书"，

而是 把工程经验结构化注入给 AI。

当规则足够清晰：

AI 才能稳定输出
项目才不会被误伤
Agent 才真正具备工程可控性