二、Claude Code 核心配置详解：settings.json 与三层记忆体系

前言当你安装好 Claude Code兴冲冲地打开它开始编程可能会遇到这些问题每次新会话都要重新交代项目背景AI 像失忆了一样AI 总是试图执行你不希望的操作比如删除文件、安装依赖不同项目的规则混在一起写 React 项目时它用 Python 风格这些问题的根源是你还没有配置 Claude Code。Anthropic 官方反复强调一个观点模型能力是地板配置质量才是天花板。花时间把配置做好比追最新模型版本更有实际收益。本文将深入讲解 Claude Code 的两大核心配置机制settings.json 权限配置和三层记忆体系帮你把 Claude Code 从能用变成好用。1. settings.json — Claude Code 的控制面板1.1 什么是 settings.jsonsettings.json是 Claude Code 的核心配置文件控制着 AI 的行为边界、权限范围和功能开关。你可以把它理解为给 AI 定的规矩——哪些事情可以直接做哪些事情需要问你哪些事情绝对禁止。1.2 配置文件的三个层级Claude Code 设计了三级配置文件体系从全局到项目级层层覆盖↓ 优先级递增后者覆盖前者同名配置最佳实践通用的安全规则放在全局配置中项目特定的配置放在项目级配置中。个人偏好如你本地的测试环境地址放在.local.json中。1.3 核心配置项详解一个典型的settings.json长这样{permissions:{allow:[Read,Write,Bash(npm *),Bash(git *),Bash(node *),Bash(python *),Bash(npx *)],deny:[Bash(rm -rf *),Bash(git push --force *),Bash(sudo *)]},model:sonnet,autoCompactThreshold:80}1.3.1 权限控制permissions这是最重要的配置决定了 AI 在执行操作时是否需要问你确认权限配置说明示例allow白名单AI 可直接执行不再弹窗确认Read— 读取文件deny黑名单AI 绝对禁止执行Bash(rm -rf *)— 禁止递归删除未配置的每次执行前都会弹窗询问用户默认行为推荐的安全配置{permissions:{allow:[Read,Write,Edit,Bash(npm *),Bash(npx *),Bash(git status),Bash(git diff *),Bash(git log *),Bash(git add *),Bash(git commit *),Bash(ls *),Bash(cat *),Bash(find *),Bash(grep *)],deny:[Bash(rm -rf *),Bash(git push --force *),Bash(git reset --hard *),Bash(sudo *),Bash(curl * | sh),Bash(wget * | sh)]}}⚠️安全提醒初学者建议保持默认设置所有操作都需确认等熟悉了 Claude Code 的行为模式后再逐步放开白名单。1.3.2 模型选择model{model:sonnet}Claude Code 支持通过别名或具体模型名切换模型模型别名适用场景特点haiku简单补全、格式化、小修改速度极快成本最低sonnet日常开发、功能实现默认推荐速度与质量最佳平衡opus复杂架构设计、疑难 Bug、算法难题推理能力最强成本较高模型选择的四种方式优先级从高到低1. claude --model opus ← 启动参数临时 2. export ANTHROPIC_MODELopus ← 环境变量 3. settings.json → model: opus ← 配置文件推荐 4. 会话中 /model 命令 ← 运行时切换1.3.3 上下文压缩阈值autoCompactThreshold{autoCompactThreshold:80}当上下文使用量达到该百分比时Claude Code 会自动压缩对话历史为摘要腾出空间。默认值通常为 80意味着上下文使用 80% 时自动压缩。 建议设置为 60~70避免等到上下文快满了才压缩——那时 AI 已经开始遗忘早期内容回答质量下降。1.3.4 其他常用配置{env:{ANTHROPIC_BASE_URL:https://api.example.com,ANTHROPIC_AUTH_TOKEN:your-api-key,HTTP_PROXY:http://127.0.0.1:7890,HTTPS_PROXY:http://127.0.0.1:7890,CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC:1},cleanupPeriodDays:30,autoMemoryEnabled:true}配置项说明ANTHROPIC_BASE_URLAPI 代理地址使用第三方服务时需要ANTHROPIC_AUTH_TOKENAPI 密钥HTTP_PROXY/HTTPS_PROXY网络代理国内用户通常需要CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC设为1禁用自动更新、遥测等非必要流量cleanupPeriodDays会话记录保留天数默认 30 天autoMemoryEnabled自动记忆开关默认true2. 三层记忆体系 — 让 AI 越用越懂你Claude Code 的每个会话默认从全新的上下文窗口开始。为了实现跨会话的知识传递官方设计了三层记忆体系每一层解决不同层次的问题2.1 第一层CLAUDE.md — 项目的入职手册CLAUDE.md 是 Claude Code 中最重要的配置文件。它就像你给新来的实习生写的项目入职手册——告诉 AI 这个项目的背景、技术栈、编码规范和当前进度。没有 CLAUDE.mdAI 每次开始工作都要花时间重新认识你的项目。有了 CLAUDE.mdAI 一启动就知道项目的全部背景效率大幅提升。2.1.1 CLAUDE.md 的三级位置Claude Code 为 CLAUDE.md 设计了三个层级同时生效、不冲突┌─────────────────────────────────────────────────────────────┐ │ 全局级 ~/.claude/CLAUDE.md │ │ → 所有项目都会读取 │ │ → 适合写个人偏好、回复语言、身份信息 │ │ 例如永远用中文回答、我是后端工程师 │ ├─────────────────────────────────────────────────────────────┤ │ 项目级 项目根目录/CLAUDE.md │ │ → 仅当前项目生效 │ │ → 适合写技术栈、架构、编码规范、进度提交 Git 团队共享 │ ├─────────────────────────────────────────────────────────────┤ │ 文件夹级 子目录/CLAUDE.md │ │ → 仅该子目录生效 │ │ → 适合写模块专属约定 │ │ 例如src/payment/CLAUDE.md 写支付模块踩过的坑 │ └─────────────────────────────────────────────────────────────┘ 优先级文件夹级 项目级 全局级 还有两个特殊位置CLAUDE.local.md项目根目录个人项目偏好不提交 Git组织级策略文件/Library/Application Support/ClaudeCode/CLAUDE.md由 IT 统一管理无法被个人排除2.1.2 编写 CLAUDE.md快速生成在项目目录启动 Claude Code输入/initAI 会自动扫描项目并生成一份 CLAUDE.md 初稿。手动编写模板# 项目名称 ## 项目概述 一句话描述这个项目做什么。 ## 技术栈 - 前端Next.js 14 TypeScript Tailwind CSS - 后端Next.js API Routes - 数据库Prisma PostgreSQL - 部署Vercel ## 项目结构 src/ ├── app/ # Next.js App Router 页面 ├── components/ # React 组件 │ ├── ui/ # 通用 UI 组件 │ └── features/ # 业务组件 ├── lib/ # 工具函数 ├── prisma/ # 数据库 Schema └── types/ # TypeScript 类型定义 ## 编码规范 - 使用函数式组件 React Hooks - 组件文件使用 PascalCase如 UserCard.tsx - 工具函数使用 camelCase - 所有数据库操作通过 Prisma Client - API 返回统一格式{ success, data?, error? } ## 构建与测试 - 安装依赖npm install - 开发模式npm run dev - 构建npm run build - 测试npm test - 类型检查npx tsc --noEmit ## 当前状态 - 用户认证模块已完成 - 商品列表 API 开发中 - 搜索功能待开发 ## 注意事项 - .env 文件包含敏感信息不要提交到 Git - prisma/dev.db 是本地数据库不提交 - 所有新功能先创建 Git 分支再开发编写原则原则说明保持简洁控制在 200 行以内过长会消耗过多上下文足够具体写使用 2 空格缩进而不是正确格式化代码写明禁忌把不要做什么也写清楚保持更新项目加了功能、踩了坑及时同步更新避免冲突不同文件中的规则不要互相矛盾进阶用法 — 导入外部文件CLAUDE.md 支持path/to/file语法导入其他文件有关项目概述请参阅 README.md 有关可用命令请参阅 package.json ## 额外规范 - Git 工作流参见 docs/git-workflow.md - API 设计参见 docs/api-design.md2.1.3 使用 .claude/rules/ 组织规则对于大型项目可以将指令拆分为多个独立文件项目根目录/ └── .claude/ └── rules/ ├── testing.md # 测试规范 ├── api-design.md # API 设计规范 ├── security.md # 安全规范 └── frontend/ ├── components.md # 组件开发规范 └── styling.md # 样式规范路径范围规则按需加载节省上下文---paths:-src/api/**/*.ts---# API 开发规则-所有 API 端点必须包括输入验证-使用标准错误响应格式-包含 OpenAPI 文档注释这样配置的规则只有在 Claude 处理src/api/下的 TypeScript 文件时才会加载。2.2 第二层Auto Memory — AI 的工作笔记本如果说 CLAUDE.md 是你主动立下的规矩那 Auto Memory 就是AI 在干活过程中默默记下的设计笔记。2.2.1 工作原理Auto Memory 让 Claude 从日常交互中自动积累知识无需手动配置你与 Claude Code 对话 │ ▼ ┌──────────────────┐ │ 后台分析对话内容 │ │ 提取有价值的信息 │ └────────┬─────────┘ │ ▼ ┌─────────────────────────────────────┐ │ 自动记忆存储 │ │ │ │ ~/.claude/projects/project/ │ │ memory/ │ │ ├── MEMORY.md ← 核心索引 │ │ ├── debugging.md ← 调试笔记 │ │ ├── api-conventions.md ← API 决策 │ │ └── ... │ └─────────────────────────────────────┘加载机制每次会话启动时先加载MEMORY.md的前 200 行或 25KB作为索引遇到具体问题时AI 按需读取对应的子文件获取详细信息不会把所有记忆一次性全部塞进上下文2.2.2 自动记忆记录什么类型含义示例user关于你的信息你是 Go 专家但不熟悉 Reactfeedback你给过的工作指导“不要 mock 数据库”、“回复要简洁”project项目相关信息进度、决策、技术选型reference外部资源索引“设计文档在 docs/design.md”2.2.3 启用与管理# 在 Claude Code 会话中输入/memory# 在菜单中选择启用 Auto Memory也可以通过配置文件控制{autoMemoryEnabled:true}管理技巧用CtrlO查看当前被加载的记忆内容记错了直接跟 AI 说忘掉刚才说的 XX它会删除用/memory打开记忆文件夹手动编辑或删除记忆文件主动说记住 XXAI 会写入自动记忆2.3 第三层自建参考文档 — 专项知识按需加载某些知识不适合全塞进 CLAUDE.md太长、太专业但 AI 需要时必须能查到。这就是第三层记忆的作用。2.3.1 典型场景docs/ ├── brand-visual.md # 品牌视觉规范颜色、字体、间距 ├── copywriting-style.md # 产品文本风格语调、术语表 └── api-conventions.md # API 约定请求响应格式、错误码在 CLAUDE.md 中加上指引## 外部参考文档 - 修改前端视觉、调颜色、调间距时 → 必读 docs/brand-visual.md - 写产品文案、按钮文字、提示语时 → 必读 docs/copywriting-style.md - 写 API、定义返回格式时 → 必读 docs/api-conventions.md这样 AI 只在需要的时候才去读完整文档既保证准确性又不占多余上下文。2.3.2 与 .claude/rules/ 的区别特性自建参考文档.claude/rules/存放位置项目任意目录.claude/rules/固定目录加载方式通过 CLAUDE.md 中的指引按需读取可通过paths字段自动按需加载适用场景专项知识设计规范、业务规则编码规范、测试规范等技术规则维护方式手动维护手动维护3. 三层记忆的协作关系三层记忆不是孤立的它们在每次会话中协同工作┌─────────────────────────────────────────────────────────────┐ │ 会话启动 │ │ │ │ │ ┌────────────┼────────────────┐ │ │ ▼ ▼ ▼ │ │ 加载 CLAUDE.md 加载 MEMORY.md 等待按需调用 │ │ (全量注入) (前200行索引) (参考文档) │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌──────────────────────────────────────────┐ │ │ │ 合并到系统上下文 │ │ │ │ CLAUDE.md明规则 记忆索引隐规则 │ │ │ └──────────────────────┬───────────────────┘ │ │ │ │ │ ▼ │ │ 开始会话交互 │ │ │ │ │ ┌───────────┼───────────┐ │ │ ▼ ▼ ▼ │ │ AI 执行任务 遇到专项知识 需要详细记忆 │ │ │ → 读参考文档 → 读记忆子文件 │ │ │ │ │ │ │ └───────────┼───────────┘ │ │ │ │ │ ▼ │ │ 会话结束 │ │ │ │ │ ▼ │ │ ┌───────────────────────┐ │ │ │ 后台分析本次对话 │ │ │ │ 提取有价值信息 │ │ │ │ 写入 Auto Memory │ │ │ └───────────────────────┘ │ └───────────────────────────────────────────────────────────────┘一句话总结第一层 CLAUDE.md你主动写的明规则全量加载优先级最高第二层 Auto MemoryAI 自己记的隐规则按需读取越用越懂你第三层参考文档手动维护的专项知识AI 遇到对应任务才读本质认知Agent 的所有记忆本质上都是在合适的时候向大模型注入压缩过的上下文。三层记忆是组织这些上下文的分层策略核心目标是在有限的上下文窗口中最大化注入有价值的信息。4. 实战配置清单4.1 新手起步配置// ~/.claude/settings.json{permissions:{allow:[Read],deny:[Bash(rm -rf *),Bash(sudo *)]},model:sonnet}先保持最小权限所有写操作和命令执行都需确认逐步熟悉后再放开。4.2 团队项目推荐配置// 项目/.claude/settings.json{permissions:{allow:[Read,Write,Edit,Bash(npm *),Bash(git status),Bash(git diff *),Bash(git add *),Bash(git commit *),Bash(npx tsc --noEmit),Bash(npm test)],deny:[Bash(rm -rf *),Bash(git push --force *),Bash(git reset --hard *),Bash(sudo *)]},model:sonnet,autoCompactThreshold:70}4.3 快速配置流程1. 安装 Claude Code npm install -g anthropic-ai/claude-code 2. 全局配置 vim ~/.claude/settings.json ← 设置基础权限和模型 3. 进入项目目录 cd your-project 4. 生成项目说明 claude /init ← 自动生成 CLAUDE.md 5. 开启自动记忆 /memory ← 选择启用 Auto Memory 6. 编辑全局偏好 /memory ← 选择全局 CLAUDE.md 写入个人偏好如永远用中文回答 7. 开始使用 直接描述需求即可5. 常见问题CLAUDE.md 写了但 AI 不遵守运行/memory确认文件已被正确加载检查文件是否在正确位置指令写得更具体“使用 2 空格缩进” 而非 “正确格式化”检查是否有跨文件的冲突规则上下文用完了怎么办命令效果适用时机/compact压缩历史为摘要保留关键决策同一任务对话过长还要继续/clear彻底清空等于重开一个任务结束开始全新任务/context查看上下文占比和各部分占用诊断什么在消耗上下文 心法宁可多/clear几次重新介绍背景也不要一直聊下去。每次/clear都是给 AI 一次重新聚焦的机会。自动记忆记错了怎么办直接告诉 AI “忘掉 XX”或者用/memory打开记忆文件夹手动删除。所有记忆文件都是纯文本 Markdown可以直接编辑。6. 总结Claude Code 的配置体系可以概括为两个核心机制机制解决的问题核心文件settings.json“AI 能做什么、不能做什么”~/.claude/settings.json三层记忆“AI 知道什么、该记住什么”CLAUDE.md Auto Memory 参考文档settings.json控制行为边界——权限白名单让日常操作更顺畅权限黑名单防止危险操作模型选择平衡性能与成本。三层记忆管理知识传递——第一层 CLAUDE.md 是全量注入的明规则第二层 Auto Memory 是按需读取的隐规则第三层参考文档是专项知识的按需加载。三者配合让 AI 越用越懂你。配置不是一次性的工作而是持续优化的过程。随着你对 Claude Code 的使用越来越深入不断调整权限、完善 CLAUDE.md、校准自动记忆AI 会逐渐从一个聪明的陌生人变成真正懂你的搭档。参考资源官方文档资源链接说明Claude Code 官方文档docs.anthropic.com/en/docs/claude-code完整使用文档Claude Code 记忆系统docs.anthropic.com/en/docs/claude-code/memory记忆系统官方指南Claude Code 权限管理docs.anthropic.com/en/docs/claude-code/permissions权限与安全配置Anthropic API 文档docs.anthropic.comAPI 参考与模型说明社区资源资源链接说明Karpathy 的 Claude Skillsgithub.com/multica-ai/andrej-karpathy-skillsKarpathy 分享的几百行通用规则