<p align="right"><font color="#3f3f3f">2025年07月28日</font></p>
> **目标**：在安全、低成本的前提下，充分发挥 Claude Code 的 “代理式编码” 能力，为单人或团队项目提供持续增益。
## 1. 理念速览
| 核心原则 | 说明 |
| --------------- | ------------------------------------------------- |
| **前置设计** | 明确上下文边界、权限模型、成本阈值 → 再接入 Claude |
| **轻量索引 & 按需加载** | 顶层 CLAUDE.md 只放导航；大文件按需 `@path` 或子目录 CLAUDE.md 引入 |
| **最小权限** | 通过 `permissions.allow/deny`、容器隔离，限制文件系统与网络访问范围 |
| **分层记忆** | 遵循「项目 > 共享 > 个人」层级，把长期规范写进项目级，个人偏好写进用户级 |
| **成本可视化** | 在 CI 或本地脚本中统计 Token & 执行时间，自动降级模型或切分任务 |
---
## 2. 安装与基础环境
- **支持系统**：macOS ≥ 10.15、Ubuntu ≥ 20.04 / Debian ≥ 10、Windows 10 (WSL)；≥ 4 GB RAM。
- **依赖**：Node ≥ 18、Bash/Zsh/Fish、可访问互联网。
- **一键安装**：
```bash
npm install -g @anthropic-ai/claude-code
claude /login # 浏览器 OAuth 鉴权
claude /doctor # 自检依赖 & 网络
```
- **关键环境变量**
| 变量 | 用途 | 建议配置 |
| ------------------------------- | ------------- | -------------------------- |
| `ANTHROPIC_API_KEY` | 访问 Claude API | GitHub/CI Secrets，严禁硬编码 |
| `ANTHROPIC_BASE_URL` | 私有网关地址 | 企业网关或代理 |
| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 限制生成 Token 上限 | 项目 `.claude/settings.json` |
| `DISABLE_TELEMETRY` | 关闭用量遥测 | 合规场景下置 `true` |
---
## 3. 分层配置与 `settings.json`
Claude Code 依次读取并覆盖下列配置文件：
1. **企业策略**（集中管控，自上而下下发）
2. **CLI 参数**（优先级最高，适合一次性覆写）
3. **项目共享** → `./.claude/settings.json`
4. **项目局部** → `./.claude/settings.local.json`（进 `.gitignore`）
5. **用户级** → `~/.claude/settings.json`
> 建议在仓库根建 `.claude/`，将允许工具、默认模型、公共 Hook 写入共享配置；个人偏好写入用户级；敏感或实验功能放 `settings.local.json`。
---
## 4. 权限 & 安全模型
- **白名单优先**：通过 `permissions.allow/deny` 精细控制对 `Write()`、`Bash()`、`Network()` 等危险动作。
- **Safe YOLO 容器**：批量格式化 / 生成样板时，可在无网容器里加 `--dangerously-skip-permissions`，速度快且不怕误删文件。
- **密钥管理**：所有 CI/仓库中统一用 Secrets；本地开发使用 `envrc` 或 `direnv` 注入。
- **日志审计**：走网关 / 代理时记录请求日志，便于安全回溯。
---
## 5. CLAUDE.md 与上下文工程
### 5.1 层级读取规则
| 读取阶段 | 触发时机 | 行为 |
| --------- | ----------- | -------------------------- |
| **启动** | 打开 Claude 时 | 从 cwd 递归向上加载所有 CLAUDE.md |
| **子目录追加** | 首次访问子目录文件 | 追加该子目录 CLAUDE.md |
| **用户级** | 始终 | 最后合并 `~/.claude/CLAUDE.md` |
冲突遵循「近处优先」。
### 5.2 `@path` 导入机制
- 会 **立即** 展开，整块内容写入提示；可递归 5 层。
- 顶层 @ 导入大文件会推高 Token 消耗，建议：
1. 顶层只写一句导航。
2. 需要时在对话中 `@docs/big-spec.md` 即时加载。
3. 定期使用 `claude token-count` 监控提示大小。
---
## 6. 多功能仓库的上下文拆分
```text
repo/
├─ CLAUDE.md # 项目索引（轻量）
├─ docs/
│ ├─ coding-style.md
│ └─ testing-guidelines.md
├─ feature-a/CLAUDE.md # A 模块规范
├─ feature-b/CLAUDE.md # B 模块规范
```
### 工作流
1. `cd feature-a && claude` → 自动加载项目索引 + feature‑a 规范。
2. 跨模块需求：对话里写 `@feature-b/README.md` 即时引入。
3. 并行任务：在 `settings.json` 的 `additionalDirectories` 加入其他模块路径，将其 CLAUDE.md 暂时暴露。
---
## 7. 子代理（Sub‑agents）与命令自动化
### 7.1 Slash Commands
- 把常用操作模板放 `.claude/commands/`。
- 例：`/project:lint-all` → 一键修复 ESLint。
### 7.2 Sub‑agents
- 在 `.claude/agents/` 建立 `sql-optimizer.md`：
```yaml
---
name: sql-optimizer
allowed_tools:
- Read()
- Bash(psql)
prompt: |
你是一名资深数据库专家，负责优化查询…
---
```
- 通过 `/agent sql-optimizer` 让 Claude 专注数据库任务。
---
## 8. CI / GitHub Actions 集成
```yaml
name: claude-audit
on: [pull_request]
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Claude Doc Audit
run: claude -p '你是文档审计员，确保改动符合 @docs/coding-style.md' \
--allowedTools "Bash(npm run lint*)" \
--model claude-3.5-haiku \
--timeout_minutes 5
```
- Scope 最小化，只给必要权限。
- 复杂任务分段调用：格式化用 Haiku，评审用 Sonnet/Opus。
---
## 9. IDE & 本地开发体验
- **VS Code 插件**：自动侦测 Claude Code，支持选中文本、Diff 视图、Alt+Cmd+K 注入上下文。
- **gh CLI**：可让 Claude 写 commit message、生成 PR 描述。
- **多模态**：桌面版可拖拽截图或设计稿进行 UI 比对。
---
## 10. 成本控制与监控
| 维度 | 建议 |
| ------------ | ----------------------------------------------- |
| **模型选择** | Haiku：格式化 / 小脚本；Sonnet/Opus：复杂重构 / 审计 |
| **Token 上限** | 项目 `.claude/settings.json` 设置 `maxOutputTokens` |
| **执行超时** | CLI `--timeout_minutes` 或 CI 步骤超时控制 |
| **用量统计** | `claude usage --since yesterday` 追踪消耗 |
---
## 11. 常见问题（FAQ）
**Q1: Claude 会一次性加载所有子目录 CLAUDE.md 吗？**
> 不会。只有在访问子目录文件时才追加其 CLAUDE.md。
**Q2: 顶层大量 @import 会不会撑爆上下文？**
> 会占用窗口。把大文件交给即时 `@file` 引入。
**Q3: 如何确保 Claude 只修改当前功能代码？**
> 在 `.claude/settings.json` 限制 `permissions.allow`，并在 cwd 使用相对路径，防止误写其他模块。
---
## 12. 参考链接与进一步阅读
- 官方博客：**Claude Code – Best Practices for Agentic Coding**
- Reddit `r/ClaudeAI` 社区模板与踩坑总结
- Connectors Directory & MCP 文档
---
> **最后一句话**：牢记 “目录分层 + 轻量索引 + 按需加载 + 最小权限 + 成本监控”，让 Claude Code 成为你的高效、可控、可信的 AI 编程伙伴。