项目设置

模块编号： 3 · 难度： 入门 · 预计时间： 45 分钟

当你接手新项目，或者想把旧代码库规范化，第一步就是给 Claude Code 铺好路。这里的核心理念是降低重复劳动，把你的脑力省下来做更有价值的事。

初始化项目记忆

当你第一次进入一个项目时，输入 /init 让 Claude 帮你做个全身扫描。它会分析你的代码结构，然后自动生成一个 CLAUDE.md 文件。这个文件相当于你项目的使用说明书。

生成的 CLAUDE.md 记得提交到 git 仓库里。不过别让它变成一个无底洞。一份高质量的 CLAUDE.md 最好控制在 200 行以内。里面只放那种几乎每次会话都用得上的全局规范。如果你有些特殊功能相关的要求，把它们单独放进对应的规则文件里。

真正有价值的信息通常是这几样：

• 技术栈和具体版本号
• 常用开发命令，比如构建、测试、代码检查
• 全局命名规范
• 项目里那些让人容易踩坑的设计

来看一个 Payment Service 项目的模板示例：

# 支付服务 (Payment Service) 项目说明

技术栈: Node.js 20, TypeScript 5, PostgreSQL 15, Express, Prisma, Jest

开发指南:
* 安装依赖: npm ci (避免使用 npm install)
* 运行测试: npm run test
* 编译项目: npm run build
* 代码检查: npm run lint

代码规范:
* 文件名使用 kebab-case，例如 payment-handler.ts
* API 响应必须包含标准的 success, data, error 字段
* 数据库迁移只允许向后兼容，不要直接删列

已知注意点:
* 本地开发时，stripe webhook 代理通过 localhost:4242 转发
* 处理订单金额统一使用分 (cents)，不要存浮点数

配置权限

用久了你就会发现，每次执行 Git 或是测试命令都要跳出来让你按确认键，这实在有点折腾。输入 /permissions 可以打开权限管理，你可以把那些高频又安全的命令加进白名单。

推荐把这几个操作预先批准：

• Bash(git *)
• Bash(npm *)
• Bash(npx jest *)

Claude 会把权限配置存在两个地方：

1. .claude/settings.json: 这是跟着项目走的，建议提交到 git 里和团队共享。
2. .claude/settings.local.json: 这是你私人的配置，只留在本地，记得把它加到 .gitignore 里。

一个团队配置文件的例子：

{
  "permissions": {
    "allow": [
      {
        "tool": "Bash",
        "command": "git *"
      },
      {
        "tool": "Bash",
        "command": "npm run *"
      }
    ],
    "deny": [
      {
        "tool": "Bash",
        "command": "git push --force"
      }
    ]
  }
}

设置和环境

项目配置其实有个加载顺序，优先级从高到低排列：

1. 管理策略
2. 命令行参数 (比如加的参数选项)
3. 本地配置 .claude/settings.local.json
4. 项目配置 .claude/settings.json
5. 全局配置 ~/.claude/settings.json

除了权限，你还可以在配置里加很多有用的参数。比如 env 帮你预设好环境变量，agent 设定默认跑哪个智能体，claudeMdExcludes 帮你过滤掉那些不需要扫描的大体积目录。还可以指定默认使用的模型和投入程度(effort)。

带上环境变量和模型设置的例子：

{
  "model": "claude-3-7-sonnet-20250219",
  "effort": 1.0,
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "claudeMdExcludes": [
    "node_modules",
    "dist",
    "coverage",
    ".git"
  ]
}

版本控制指南

配置完一堆东西，到底哪些该提交，哪些该自己留着？照这个清单来。

提交的文件：

• .claude/settings.json: 团队通用的权限和配置。
• CLAUDE.md: 项目的全局说明书。
• .claude/rules/: 特定的开发规则。
• .claude/skills/: 扩展的能力脚本。
• .claude/agents/: 自定义智能体配置。

不提交的文件：

• .claude/settings.local.json: 你个人的偏好和私有令牌。
• 自动生成的本地记忆缓存。

模板区

这里准备了两个现成的内容，你可以直接拿去用在新项目里。

项目 settings.json 起步配置

这是一个开箱即用的配置文件，包含了安全白名单，还加了一个每次用完工具自动帮你格式化代码的钩子。

{
  "permissions": {
    "allow": [
      { "tool": "Bash", "command": "git status" },
      { "tool": "Bash", "command": "git diff *" },
      { "tool": "Bash", "command": "git add *" },
      { "tool": "Bash", "command": "npm install" },
      { "tool": "Bash", "command": "npm run test" }
    ],
    "deny": [
      { "tool": "Bash", "command": "git push -f" },
      { "tool": "Bash", "command": "rm -rf *" }
    ]
  },
  "hooks": {
    "PostToolUse": "npm run lint -- --fix"
  }
}

新项目上手清单

当你执行完 /init 并准备修改 CLAUDE.md 时，可以按这个清单逐一确认：

• 包管理器: 统一用 npm、yarn 还是 pnpm？
• 运行命令: 怎么把项目跑起来？
• 测试指令: 跑全量测试和单元测试用什么命令？
• 分支命名: feature, bugfix 分支有没有固定前缀要求？
• 环境变量: 开发环境的配置文件该去哪里找？

用配置生成器试试

下面这个工具可以帮你快速生成项目配置文件。填好表单，右边会实时生成内容，可以直接复制或下载：

项目名称 *

技术栈

测试命令

构建命令

Lint 命令

代码规范

自定义指令

CLAUDE.md

# 项目名称

测验

📝

测验时间

第 1/3 题

运行 /init 后生成的 CLAUDE.md 建议控制在多少行以内？

← 记忆与 CLAUDE.md · 下一个：命令深入 →