配置说明

Claude Code 通过多层配置系统提供灵活的定制能力。本指南详细介绍各种配置选项和最佳实践。

配置文件结构

bash

.claude/
├── settings.json          # 全局配置
├── settings.local.json    # 个人配置（可选）
├── CLAUDE.md             # 系统入口配置
├── COMMANDS.md           # 命令执行框架
├── FLAGS.md              # 标志系统参考
├── PRINCIPLES.md         # 核心原则
├── RULES.md              # 操作规则
├── MCP.md               # MCP服务器集成
├── PERSONAS.md          # 角色系统参考
├── ORCHESTRATOR.md      # 智能路由系统
├── MODES.md             # 操作模式
├── GRAPHITI.md          # Graphiti工具指令
├── BASIC.md             # 基础指南
├── STRUCTURE.md         # 目录结构说明
├── README.md            # 项目说明
│
├── agents/              # AI代理配置
│   ├── master.md        # 主代理
│   ├── orchestrator.md  # 编排器代理
│   ├── planner.md      # 规划代理
│   ├── executor.md     # 执行代理
│   ├── analyst.md      # 分析代理
│   ├── debugger.md     # 调试代理
│   ├── architect.md    # 架构代理
│   ├── dev.md         # 开发代理
│   ├── reviewer.md     # 审查代理
│   ├── qa.md          # QA代理
│   ├── writer.md      # 写作代理
│   ├── ui.md          # UI代理
│   ├── ux-expert.md   # UX专家代理
│   ├── pm.md          # 项目经理代理
│   ├── po.md          # 产品负责人代理
│   └── sm.md          # Scrum Master代理
│
├── agent-teams/         # 代理团队配置
│   ├── team-all.yaml        # 完整团队配置
│   ├── team-fullstack.yaml  # 全栈团队配置
│   ├── team-ide-minimal.yaml # IDE最小团队配置
│   └── team-no-ui.yaml      # 无UI团队配置
│
├── commands/sc/         # 斜杠命令定义
│   ├── analyze.md      # /analyze命令
│   ├── build.md        # /build命令
│   ├── cleanup.md      # /cleanup命令
│   ├── design.md       # /design命令
│   ├── document.md     # /document命令
│   ├── estimate.md     # /estimate命令
│   ├── explain.md      # /explain命令
│   ├── git.md         # /git命令
│   ├── implement.md    # /implement命令
│   ├── improve.md      # /improve命令
│   ├── index.md        # /index命令
│   ├── load.md         # /load命令
│   ├── spawn.md        # /spawn命令
│   ├── task.md         # /task命令
│   ├── test.md         # /test命令
│   ├── troubleshoot.md # /troubleshoot命令
│   └── workflow.md     # /workflow命令
│
├── checklists/          # 检查清单
│   ├── architect-checklist.md
│   ├── change-checklist.md
│   ├── pm-checklist.md
│   ├── po-master-checklist.md
│   ├── story-dod-checklist.md
│   └── story-draft-checklist.md
│
├── tasks/               # 任务模板
│   ├── advanced-elicitation.md
│   ├── brownfield-create-epic.md
│   ├── brownfield-create-story.md
│   ├── correct-course.md
│   ├── create-brownfield-story.md
│   ├── create-deep-research-prompt.md
│   ├── create-doc.md
│   ├── create-next-story.md
│   ├── document-project.md
│   ├── execute-checklist.md
│   ├── facilitate-brainstorming-session.md
│   ├── generate-ai-frontend-prompt.md
│   ├── index-docs.md
│   ├── kb-mode-interaction.md
│   ├── review-story.md
│   ├── shard-doc.md
│   └── validate-next-story.md
│
├── security/            # 安全配置
│   ├── README.md
│   └── security-checklist.md

│

核心配置文件

settings.json (全局配置)

全局配置文件定义了系统级别的设置和默认权限：

json

{
  "permissions": {
    "file_operations": {
      "read": true,
      "write": true,
      "delete": false,
      "create": true
    },
    "code_analysis": {
      "static_analysis": true,
      "security_scan": true,
      "performance_check": true
    },
    "git_operations": {
      "read_history": true,
      "create_branch": false,
      "commit": false,
      "push": false
    },
    "system_operations": {
      "process_management": false,
      "network_access": true,
      "file_system_access": true
    }
  },
  "behavior": {
    "auto_save": true,
    "auto_backup": true,
    "confirm_destructive": true
  },
  "cleanup": {
    "auto_cleanup": true,
    "retention_days": 30,
    "max_log_size": "100MB"
  },
  "ui": {
    "theme": "auto",
    "language": "zh-CN",
    "verbose_output": false
  }
}

settings.local.json (个人配置)

个人配置文件用于覆盖全局设置和添加个人特定的权限：

json

{
  "permissions": {
    "development": {
      "flutter_development": true,
      "dart_analysis": true,
      "nodejs_development": true,
      "typescript_support": true,
      "python_development": false
    },
    "infrastructure": {
      "docker_operations": true,
      "kubernetes_operations": true,
      "cloud_deployment": false
    },
    "databases": {
      "sql_operations": true,
      "nosql_operations": true,
      "migration_management": true
    }
  },
  "environment": {
    "preferred_editor": "vscode",
    "terminal_shell": "zsh",
    "debug_mode": false
  },
  "mcp_services": {
    "context7": {
      "enabled": true,
      "auto_activate": true
    },
    "sequential": {
      "enabled": true,
      "complexity_threshold": 0.7
    },
    "magic": {
      "enabled": false
    },
    "playwright": {
      "enabled": true,
      "headless": true
    }
  },
  "wave_system": {
    "enabled": true,
    "auto_activate": true,
    "max_stages": 5
  }
}

项目文档配置

CLAUDE.md (项目说明)

项目主说明文件，帮助 AI 理解项目背景：

markdown

# 项目名称：Flutter 电商应用

## 项目概述
这是一个基于 Flutter 开发的跨平台电商移动应用，支持商品浏览、购物车、订单管理等核心电商功能。

## 技术栈
- **前端**: Flutter 3.x, Dart 3.x
- **状态管理**: Provider + Riverpod
- **网络**: Dio + Retrofit
- **数据库**: SQLite (本地) + PostgreSQL (服务端)
- **缓存**: Hive (本地) + Redis (服务端)
- **认证**: JWT + OAuth 2.0

## 项目结构

lib/ ├── main.dart # 应用入口 ├── app/ # 应用配置 ├── core/ # 核心功能 ├── features/ # 功能模块 │ ├── auth/ # 认证 │ ├── product/ # 商品 │ ├── cart/ # 购物车 │ └── order/ # 订单 ├── shared/ # 共享组件 └── utils/ # 工具类


## 开发流程
1. **规划阶段**: 使用规划师进行功能设计
2. **实现阶段**: 使用执行器进行编码
3. **测试阶段**: 编写单元测试和集成测试
4. **审查阶段**: 代码审查和质量检查
5. **部署阶段**: CI/CD 自动化部署

## 编码规范
- 遵循 Dart 官方编码规范
- 使用 effective_dart 静态分析
- 每个功能模块独立，松耦合设计
- 统一的错误处理和日志记录

.ai-rules/ 目录配置

product.md (产品文档)

yaml

---
title: "Flutter电商应用产品文档"
description: "产品愿景、功能和用户体验设计"
include_in_context: true
---

# 产品愿景
打造用户体验优秀的移动电商平台，提供便捷的购物体验。

## 目标用户
- 主要用户：18-45岁移动购物用户
- 次要用户：商家和平台管理员

## 核心功能

### 用户功能
- **账户管理**: 注册、登录、个人资料
- **商品浏览**: 分类浏览、搜索、筛选
- **购物流程**: 加购物车、下单、支付
- **订单管理**: 订单查看、物流跟踪
- **用户服务**: 客服咨询、评价反馈

### 商家功能
- **商品管理**: 上架、编辑、库存管理
- **订单处理**: 订单确认、发货管理
- **数据分析**: 销售统计、用户分析

## 用户体验原则
- 界面简洁直观
- 操作流程简化
- 响应速度快
- 离线功能支持

tech.md (技术文档)

yaml

---
title: "技术栈和开发规范"
description: "项目技术选型和开发约定"
include_in_context: true
---

# 技术架构

## 前端技术栈
- **Flutter**: 3.16.x - 跨平台UI框架
- **Dart**: 3.2.x - 编程语言
- **Provider**: 6.x - 状态管理
- **Riverpod**: 2.x - 高级状态管理
- **Dio**: 5.x - HTTP客户端
- **Hive**: 2.x - 本地数据库
- **Flutter Hooks**: UI钩子

## 后端技术栈
- **Node.js**: 18.x - 运行时环境
- **Express**: 4.x - Web框架
- **TypeScript**: 5.x - 类型检查
- **PostgreSQL**: 15.x - 主数据库
- **Redis**: 7.x - 缓存数据库
- **JWT**: 认证方案

## 开发工具
- **IDE**: VS Code + Flutter插件
- **版本控制**: Git + GitHub
- **CI/CD**: GitHub Actions
- **容器化**: Docker + Docker Compose
- **部署**: Kubernetes

## 开发规范

### 代码规范
- 遵循 Dart Style Guide
- 使用 effective_dart 规则
- 类名使用 PascalCase
- 方法名使用 camelCase
- 常量使用 SCREAMING_SNAKE_CASE

### 项目约定
- 每个功能独立模块
- 统一的错误处理
- 标准化的API接口
- 完整的单元测试覆盖

### Git 工作流
- main: 生产环境分支
- develop: 开发分支
- feature/*: 功能分支
- hotfix/*: 热修复分支

structure.md (结构文档)

yaml

---
title: "项目结构和文件组织"
description: "代码组织方式和文件命名约定"
include_in_context: true
---

# 项目结构

## 目录组织

project/ ├── lib/ # 源代码 │ ├── main.dart # 应用入口 │ ├── app/ # 应用级配置 │ │ ├── app.dart # 应用主类 │ │ ├── routes/ # 路由配置 │ │ └── theme/ # 主题配置 │ ├── core/ # 核心功能 │ │ ├── constants/ # 常量定义 │ │ ├── errors/ # 错误处理 │ │ ├── network/ # 网络层 │ │ └── utils/ # 工具函数 │ ├── features/ # 业务功能 │ │ ├── auth/ # 认证模块 │ │ ├── product/ # 商品模块 │ │ ├── cart/ # 购物车模块 │ │ └── order/ # 订单模块 │ └── shared/ # 共享组件 │ ├── widgets/ # UI组件 │ ├── models/ # 数据模型 │ └── services/ # 共享服务 ├── test/ # 测试文件 ├── assets/ # 资源文件 ├── android/ # Android配置 └── ios/ # iOS配置


## 功能模块结构
每个功能模块遵循以下结构：

feature/ ├── data/ # 数据层 │ ├── datasources/ # 数据源 │ ├── models/ # 数据模型 │ └── repositories/ # 仓储实现 ├── domain/ # 领域层 │ ├── entities/ # 实体 │ ├── repositories/ # 仓储接口 │ └── usecases/ # 用例 └── presentation/ # 展示层 ├── pages/ # 页面 ├── widgets/ # 组件 └── providers/ # 状态管理


## 命名约定

### 文件命名
- Dart文件: `snake_case.dart`
- 页面文件: `feature_page.dart`
- 组件文件: `feature_widget.dart`
- 模型文件: `feature_model.dart`

### 类命名
- 页面类: `FeaturePage`
- 组件类: `FeatureWidget`
- 模型类: `FeatureModel`
- 服务类: `FeatureService`

### 资源文件
- 图片: `assets/images/feature_name.png`
- 图标: `assets/icons/icon_name.svg`
- 字体: `assets/fonts/font_name.ttf`

代理配置

每个代理都有独立的配置文件，定义其行为和能力：

agents/planner.md

yaml

---
name: planner
description: 功能规划和需求分析专家
activation_patterns:
  - "规划"
  - "设计"
  - "需求"
  - "功能"
capabilities:
  - requirements_analysis
  - technical_design
  - task_breakdown
mode: planning_only
---
# 规划师配置
...

MCP 服务配置

Context7 服务

json

{
  "context7": {
    "enabled": true,
    "auto_activate": true,
    "libraries": {
      "flutter": true,
      "dart": true,
      "nodejs": true
    },
    "documentation_sources": [
      "official_docs",
      "community_guides",
      "best_practices"
    ]
  }
}

Sequential 服务

json

{
  "sequential": {
    "enabled": true,
    "complexity_threshold": 0.7,
    "max_analysis_depth": 5,
    "thinking_modes": [
      "systematic_analysis",
      "problem_decomposition",
      "solution_evaluation"
    ]
  }
}

Wave 系统配置

json

{
  "wave_system": {
    "enabled": true,
    "auto_activation": {
      "complexity_threshold": 0.7,
      "file_count_threshold": 20,
      "operation_type_threshold": 2
    },
    "orchestration": {
      "max_stages": 5,
      "stage_timeout": 300,
      "parallel_execution": true
    },
    "quality_gates": {
      "code_review": true,
      "testing": true,
      "security_check": true
    }
  }
}

权限管理

权限层级

只读权限: 文件读取、代码分析
基础权限: 文件创建、编辑
开发权限: 项目构建、测试运行
高级权限: 系统操作、部署管理

危险操作保护

json

{
  "security": {
    "confirm_destructive": true,
    "forbidden_operations": [
      "system_shutdown",
      "file_deletion_bulk",
      "network_security_changes"
    ],
    "whitelist_paths": [
      "lib/",
      "test/",
      "assets/"
    ]
  }
}

监控和日志

日志配置

json

{
  "logging": {
    "level": "info",
    "file_path": "logs/claude.log",
    "max_file_size": "10MB",
    "backup_count": 5,
    "format": "{timestamp} [{level}] {message}"
  }
}

性能监控

json

{
  "monitoring": {
    "performance_tracking": true,
    "response_time_threshold": 5000,
    "memory_usage_limit": "1GB",
    "cpu_usage_limit": 80
  }
}

自定义配置

环境变量

bash

# Claude Code 配置
export CLAUDE_CONFIG_PATH="/Users/username/.claude"
export CLAUDE_LOG_LEVEL="info"
export CLAUDE_DEBUG_MODE="false"

# MCP 服务配置
export MCP_CONTEXT7_ENABLED="true"
export MCP_SEQUENTIAL_ENABLED="true"
export MCP_MAGIC_ENABLED="false"

配置验证

bash

# 验证配置文件
claude --validate-config

# 检查权限设置
claude --check-permissions

# 测试 MCP 服务连接
claude --test-mcp

配置最佳实践

1. 分层配置

全局配置用于通用设置
本地配置用于个人定制
项目配置用于特定需求

2. 权限最小化

只启用必要的权限
定期审查权限设置
使用白名单限制范围

3. 服务优化

根据项目需求启用MCP服务
调整Wave系统阈值
监控性能指标

4. 安全考虑

启用危险操作确认
定期备份配置文件
使用版本控制管理配置

配置文件支持热重载，修改后无需重启即可生效

配置说明 ​

配置文件结构 ​

核心配置文件 ​

settings.json (全局配置) ​

settings.local.json (个人配置) ​

项目文档配置 ​

CLAUDE.md (项目说明) ​

.ai-rules/ 目录配置 ​

product.md (产品文档) ​

tech.md (技术文档) ​

structure.md (结构文档) ​

代理配置 ​

agents/planner.md ​

MCP 服务配置 ​

Context7 服务 ​

Sequential 服务 ​

Wave 系统配置 ​

权限管理 ​

权限层级 ​

危险操作保护 ​

监控和日志 ​

日志配置 ​

性能监控 ​

自定义配置 ​

环境变量 ​

配置验证 ​

配置最佳实践 ​

1. 分层配置 ​

2. 权限最小化 ​

3. 服务优化 ​

4. 安全考虑 ​

配置说明

配置文件结构

核心配置文件

settings.json (全局配置)

settings.local.json (个人配置)

项目文档配置

CLAUDE.md (项目说明)

.ai-rules/ 目录配置

product.md (产品文档)

tech.md (技术文档)

structure.md (结构文档)

代理配置

agents/planner.md

MCP 服务配置

Context7 服务

Sequential 服务

Wave 系统配置

权限管理

权限层级

危险操作保护

监控和日志

日志配置

性能监控

自定义配置

环境变量

配置验证

配置最佳实践

1. 分层配置

2. 权限最小化

3. 服务优化

4. 安全考虑