# Claude Code 个人配置

`Claude Code` `开发配置` `斜杠命令` `自定义代理` `最佳实践`

# Claude Code 配置

[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 的个人配置，提供开发规范、斜杠命令、自定义代理和特定语言技能。

## 包含内容

```
claude-code/
├── CLAUDE.md                    # 共享运行时代理指令（同步到 ~/.claude/CLAUDE.md 和 ~/.codex/AGENTS.md）
├── CLAUDE.local.md              # 本仓库的本地操作说明（非运行时指令来源）
├── commands/                    # 斜杠命令
│   ├── fix-issue.md             # /fix-issue <id> - 定位并修复问题
│   ├── git-commit.md            # /git-commit - 规范化提交工作流
│   ├── handoff.md               # /handoff - 生成会话交接提示
│   └── rewrite-history.md       # /rewrite-history - 整理分支提交记录
├── agents/                      # 自定义子代理
│   ├── code-reviewer.md         # 审查代码质量与安全性
│   ├── debugger.md              # 失败根因分析
│   ├── refactorer.md            # 干净重构并完整迁移
│   └── test-writer.md           # 编写验证正确性的测试
├── .claude/
│   └── skills/                  # 语言和工具最佳实践
│       ├── python-best-practices/
│       ├── typescript-best-practices/
│       ├── react-best-practices/
│       ├── go-best-practices/
│       ├── zig-best-practices/
│       ├── playwright-best-practices/
│       ├── tamagui-best-practices/
│       ├── tilt/
│       ├── web-fetch/
│       ├── axe-ios-simulator/
│       └── zig-docs/
├── scripts/                     # 工具脚本
│   ├── install-symlinks.sh      # 安装辅助脚本
│   └── sync-codex.sh            # 将 Claude 命令和技能同步/检查到 Codex
├── codex-overrides/
│   └── skills/                  # 上游同步后应用的 Codex 专属技能覆盖
├── settings/                    # 配置文件
├── statusline/                  # 状态栏配置
└── analytics/                   # 使用分析（子模块）
```

## 安装

### 通过 Stow（推荐）

本仓库是使用 GNU Stow 的 dotfiles 仓库的子模块：

```bash
cd ~/code/dotfiles
stow -v -R -t ~ claude
```

`claude` stow 包会将本仓库内容以符号链接方式挂载。

### 手动符号链接

```bash
mkdir -p ~/.claude
ln -sf "$(pwd)/CLAUDE.md" ~/.claude/CLAUDE.md
ln -sf "$(pwd)/commands" ~/.claude/commands
ln -sf "$(pwd)/agents" ~/.claude/agents
ln -sf "$(pwd)/.claude/skills" ~/.claude/skills
```

## 命令

在 Claude Code 中使用 `/命令名` 调用：

| 命令 | 说明 |
|---------|-------------|
| `/fix-issue <id>` | 按 ID 查找并修复问题，包含测试和 PR 描述 |
| `/git-commit` | 审查变更并创建规范化提交 |
| `/handoff` | 生成供其他代理使用的独立交接提示 |
| `/rewrite-history` | 以清晰的叙述性历史重写分支提交 |

## 代理

专注于特定任务的自定义子代理。Claude Code 会在适当时机自动委托给这些代理：

| 代理 | 用途 |
|-------|---------|
| `code-reviewer` | 审查代码变更的质量、安全性和项目规范 |
| `debugger` | 通过根因分析排查故障 |
| `refactorer` | 以清晰的断点和完整迁移重构代码 |
| `test-writer` | 编写验证正确性而非凑断言的测试 |

## 技能

根据文件上下文自动加载的语言和工具专属最佳实践：

| 上下文 | 技能 |
|---------|-------|
| Python（`.py`、`pyproject.toml`） | python-best-practices |
| TypeScript（`.ts`、`.tsx`） | typescript-best-practices |
| React（`.tsx`、`.jsx`、`@react` 导入） | react-best-practices |
| Go（`.go`、`go.mod`） | go-best-practices |
| Zig（`.zig`、`build.zig`） | zig-best-practices |
| Playwright（`@playwright/test`） | playwright-best-practices |
| Tamagui（`@tamagui` 导入） | tamagui-best-practices |
| Tilt（`Tiltfile`） | tilt |

## 运行时配置

- 基础配置：`claude-code/settings/settings.json`
- 本地覆盖：`~/.claude/settings.local.json`
- 生成的运行时文件：`~/.claude/settings.json`（由 `bin/bin/claude-settings-merge --fix` 生成）
- 合并行为：对象键递归合并；`permissions.allow` 和 `permissions.additionalDirectories` 追加本地条目而不删除基础条目；其他数组以本地值替换。

## 指令权威来源

- 共享代理行为保存在 `claude-code/CLAUDE.md`。
- 本地仓库说明和个人操作指引保存在 `claude-code/CLAUDE.local.md`。
- 不要将仅限本地的内容移入 `claude-code/CLAUDE.md`；该文件会同步到 `~/.claude/CLAUDE.md` 和 `~/.codex/AGENTS.md`。

## Codex 资产同步

```bash
# 仅检查漂移（退出码 0 表示干净，2 表示漂移，1 表示错误）
claude-code/scripts/sync-codex.sh --check

# 应用同步并清理过期的托管条目（命令 + 技能）
claude-code/scripts/sync-codex.sh
```

Codex 技能同步经过精心整理：

- 上游 Claude 用户技能优先同步
- 插件技能次之同步，根据 `claude-code/scripts/sync-codex.skill-policy.tsv` 选择性剔除
- `claude-code/codex-overrides/skills/` 中的 Codex 专属覆盖最后同步，名称冲突时优先生效

## 核心原则

`CLAUDE.md` 规范强调：

- **类型优先开发**：先定义类型再实现逻辑；让非法状态无法表示
- **函数式风格**：优先使用不可变性、纯函数和显式数据流
- **最小化变更**：只实现所请求的内容；避免未请求的功能或重构
- **错误处理**：在每一层处理或返回错误；以清晰的信息响亮地失败
- **测试完整性**：测试验证正确性，而非仅满足断言
- **干净重构**：原子性地更新所有调用方；彻底删除被取代的代码

## 作者

由 Allen Eubank（Big Boss）创建

## 许可证

采用 Apache License 2.0 许可。详见 [LICENSE](LICENSE)。