154 lines
6.0 KiB
Markdown
154 lines
6.0 KiB
Markdown
# 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)。 |