claude-config-optimizer

Claude 配置优化技能

Claude Code 配置优化的规则与跟踪。

1. 配置文件位置

配置通过 Nix 以声明式方式管理（programs.claude-code home-manager 模块）。

事实来源：

• @~/ghq/github.com/i9wa4/dotfiles/nix/home-manager/agents/claude-code.nix
• @~/ghq/github.com/i9wa4/dotfiles/nix/home-manager/agents/

目标位置	来源	管理方
~/.claude/settings.json	根据 Nix 属性生成	claude-code.nix
~/.claude/CLAUDE.md	根据 AGENTS.md + CLAUDE.md 片段生成	instruction-artifacts.nix
~/.claude/rules/	nix/home-manager/agents/rules/	claude-code.nix
~/.claude/agents/	nix/home-manager/agents/subagents/	claude-code.nix
~/.claude/scripts/	nix/home-manager/agents/scripts/	claude-code.nix
~/.claude/skills/	多个 flake 输入 + 本地文件	agent-skills.nix
MCP 服务	nix/home-manager/agents/mcp-servers.nix	claude-code.nix

2. 获取 CHANGELOG

2.1. 检测本地版本

始终先检测已安装的版本：

claude --version

这会返回本地安装的版本（例如 2.1.72 (Claude Code)）。 所有 CHANGELOG 分析都必须限定在此版本及更早版本。 不得报告比本地安装版本更新的版本中的功能或变更。

2.2. 从 GitHub 获取

FILE=$(mkmd --dir tmp --label claude-code-changelog)
gh api repos/anthropics/claude-code/contents/CHANGELOG.md \
  --jq '.content' | base64 -d > "$FILE"

然后读取文件，但只分析截至本地版本（含本地版本）的章节。

3. CHANGELOG 操作

重要：以下所有操作都限定在本地安装的版本。 忽略 claude --version 中版本之后的所有 CHANGELOG 章节。

3.1. 最新版本摘要

1. 使用 claude --version 检测本地版本
2. 使用上述命令获取 CHANGELOG
3. 提取 ## <local-version> 章节（而非第一个章节）
4. 将变更分类为：
   • 新功能（Added）
   • Bug 修复（Fixed）
   • 改进（Improved/Changed）
   • 弃用项（Deprecated）
5. 用日语简要说明

3.2. 版本差异

1. 使用 claude --version 检测本地版本
2. 询问用户起始版本（结束版本默认为本地版本）
3. 提取起始版本与本地版本之间（含两者）的所有章节
4. 总结累计变更
5. 强调破坏性变更和弃用项

3.3. 检测破坏性变更

1. 使用 claude --version 检测本地版本
2. 搜索截至本地版本的章节，查找：Deprecated、Removed、 Breaking、Changed
3. 列出受影响的设置和迁移路径
4. 检查用户配置中是否存在受影响的设置

4. 规范参考

如需详细了解 Claude Code 规范、功能和用法：

• 你必须：通过 Task 工具使用 claude-code-guide 子 Agent
• 查询示例：钩子、MCP 服务、设置、IDE 集成

Task tool with subagent_type: claude-code-guide

5. 设置类别

类别	示例
显示	showTurnDuration、language
行为	respectGitignore、autoUpdate
工具	disallowedTools、allowedTools
MCP	MCP 服务配置
钩子	PreToolUse、PostToolUse、Stop hooks
计划	plansDirectory

6. CLAUDE.md 设计指南

• 你必须：只关注角色设定和核心指南
• 你必须：将详细规则拆分到 rules/ 中
• 绝不：在启动时包含不必要的信息 （参考链接、用法详情）

6.1. 包含与排除

包含	排除
Claude 无法猜出的 Bash 命令	Claude 通过阅读代码就能弄清楚的内容
与默认设置不同的代码风格规则	Claude 已知的标准语言惯例
测试说明和首选测试运行器	详细的 API 文档（改为链接到文档）
仓库规范（分支命名、PR 惯例）	经常变化的信息
项目特有的架构决策	长篇解释或教程
开发环境注意事项（必需的环境变量）	逐个文件介绍代码库
常见陷阱或不明显的行为	“编写整洁的代码”这类不言自明的做法

逐条检查：“删掉这条会导致 Claude 犯错吗？”如果不会，就删掉。

6.2. @import 语法

CLAUDE.md 可以导入其他文件：

See @README.md for project overview and @package.json for available npm
commands.

# Additional Instructions

- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

6.3. CLAUDE.md 位置

位置	范围
~/.claude/CLAUDE.md	所有 Claude 会话（全局）
./CLAUDE.md	项目根目录 — 提交到 git 与团队共享
./CLAUDE.local.md	项目根目录 — 添加到 .gitignore 以保存个人覆盖设置
父目录	适用于 monorepo（自动加载）
子目录	在处理其中的文件时按需加载

7. 配置用法

类型	加载时机	用途
CLAUDE.md / rules/	启动时完整加载	始终应用的全局规则
commands/	用户显式调用	预定义提示词、工作流
skills/	由对话自动触发	专业知识
agents/	通过 Task 工具委派	独立上下文

8. 优化检查清单

8.1. CLAUDE.md 审查

编辑 CLAUDE.md 时检查以下内容：

• 角色定义是否简洁？
• 是否确实需要始终遵守基本规则？
• 能否将详细说明移至 rules/ 或 skills/？
• 是否已将参考链接移至 skills？
• 每一行是否都通过“删掉这条 → Claude 会犯错吗？”的测试？
• 是否使用 @imports 导入较长的文档章节，而不是内联内容？
• 文件是否足够简短，避免 Claude 忽略埋在中间的规则？

8.2. 权限系统审查

检查 settings.json 的权限块：

• deny 规则是否使用现代语法 Bash(cmd *)，而非已弃用的 :*？
• 是否屏蔽了关键命令（git push、git rebase、git reset、rm、sudo）？
• 是否屏蔽了 git -C * 以防止跨仓库操作？
• defaultMode 是否合适（"plan" 或 "dontAsk"）？
• 是否屏蔽了敏感路径（secrets、.env、.ssh、keys、tokens）？
• allow 规则是否必要，还是 defaultMode 已能满足需求？

9. Skill 和 Agent Frontmatter 参考

9.1. Skill Frontmatter（SKILL.md）

---
name: skill-name
description: |
  When to trigger this skill.
  Use when:
  - condition 1
  - condition 2
disable-model-invocation: true # For workflows with side effects (manual invoke only)
---

• disable-model-invocation: true — 禁止自动触发；用户必须通过 /skill-name 显式调用。适用于会产生副作用的工作流。
• 使用 $ARGUMENTS 调用参数化工作流：/fix-issue 1234

9.2. Agent Frontmatter（.claude/agents/*.md）

---
name: agent-name
description: What this agent does and when to use it
tools: Read, Grep, Glob, Bash # Restrict available tools
model: opus # Optional: specify model
isolation: worktree # Run in isolated git worktree (v2.1.49+)
background: true # Always run as background task (v2.1.49+)
---

10. 文件结构维护

在 rules/、skills/、agents/ 或 commands/ 中添加或删除文件时：

• 必须：更新 CLAUDE.md 第 4 节中对应的表格
• 必须：确保表格按字母顺序排列或进行逻辑分组
• 重要：更改后验证实际文件与文档一致

11. 优化跟踪

上次审核的 Claude Code 版本：v2.1.94（2026-04-09）

11.1. 已应用的优化

• 精简角色定义
• 将规则拆分到 rules/ 目录
• 将技能拆分到 skills/ 目录
• 将 Agent 拆分到 agents/ 目录
• 将命令拆分到 commands/ 目录
• 将参考链接移至技能中
• language 设置——设为 "English"
• ENABLE_TOOL_SEARCH 环境变量——设为 "auto:3"
• 已审核权限系统——确认沙盒绕过修复（v2.1.34）
• 已迁移权限拒绝规则——将已弃用的 :* 替换为现代 * 语法
• 快速模式——Opus 4.6 可用（v2.1.36）
• Agent 团队——通过 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 启用
• 自动记忆——默认启用（v2.1.32）
• 已移除 CLAUDE_CODE_ENABLE_TASKS 环境变量（任务默认启用）
• 已移除 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC——启用 Remote Control 和功能标志刷新（v2.1.51+）
• CLAUDE_AUTOCOMPACT_PCT_OVERRIDE = "70"——上下文使用量达到 70% 时自动压缩
• includeGitInstructions = false——禁用内置 Git 指令； 自定义 rules/github.md 是唯一权威来源（v2.1.69）
• CLAUDE_CODE_SUBPROCESS_ENV_SCRUB = "1"——从子进程中剥离凭据 （v2.1.83）
• showThinkingSummaries = true——默认值更改后（v2.1.89），需要明确选择启用 （交互式会话中默认不再生成思考摘要）
• CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING——有意保持未设置 （自适应思考保持开启）。结合启动时的 /effort high，与 v2.1.94 中正式确立的团队版／企业版默认设置一致。完整理由和 HN 讨论链接请参阅 references/changelog-tracking.md 中的决策日志。

11.2. 待考虑事项

• SQL 架构验证——已移至 databricks 技能（第 8 节）
• TeammateIdle/TaskCompleted 钩子——用于未来的 Agent 工作流自动化
• Agent 记忆 frontmatter——为有状态 Agent 设置 memory: user|project|local
• Task(agent_type) 限制——增强生成子 Agent 的安全性
• WorktreeCreate/WorktreeRemove 钩子——为 worktree 隔离自定义 VCS 设置／清理流程（v2.1.50）
• ConfigChange 钩子——对设置更改进行安全审计（v2.1.49）
• 在 Agent 定义中设置 isolation: worktree——为每个 Agent 创建隔离的 Git worktree （v2.1.49、v2.1.50）
• PostCompact 钩子——归档／分析压缩摘要；包含 compact_summary 字段（v2.1.76）
• Elicitation/ElicitationResult 钩子——拦截 MCP 服务的结构化输入请求（v2.1.76）
• 钩子的条件 if 字段——使用权限规则语法进行筛选，降低进程生成开销 （v2.1.85）
• StopFailure 钩子——记录 API 错误（速率限制、身份验证失败）（v2.1.78）
• UserPromptSubmit 钩子中的 hookSpecificOutput.sessionTitle（v2.1.94）—— 根据每条提示词动态设置会话／tmux 窗格标题
• CLAUDE_CODE_NO_FLICKER=1 环境变量（v2.1.89）——无闪烁的备用屏幕 渲染；若观察到渲染异常，再重新评估

有关决策日志（“不采用”）和各版本变更日志， 请参阅变更日志跟踪。

12. 响应格式（CHANGELOG）

# Claude Code vX.X.X

## New Features
- [Feature]: [Description]

## Bug Fixes
- [Fix description]

## Improvements
- [Improvement description]

## Deprecated/Removed
- [Affected settings and migration path]

---
Source: https://github.com/anthropics/claude-code

13. site2skill 用法

将文档网站转换为 Claude Agent Skills。

要求：Python 3.10+、wget（brew install wget）

uvx --from git+https://github.com/laiso/site2skill site2skill <URL> <SKILL_NAME>

# Example
uvx --from git+https://github.com/laiso/site2skill site2skill https://docs.pay.jp/v1/ payjp

选项：

• --output, -o——输出目录（默认：.claude/skills）
• --skill-output——保存 .skill 文件的位置（默认：当前目录）
• --skip-fetch——跳过下载（重用现有文件）
• --clean——完成后删除临时文件

若要更新现有技能文档，请在不使用 --skip-fetch 的情况下重新运行。

14. 参考链接

官方文档：

• 最佳实践：https://code.claude.com/docs/en/best-practices.md
• 文档地图：https://code.claude.com/docs/en/claude_code_docs_map.md

社区资源：

• Claude Code 配置： https://blog.atusy.net/2025/12/15/claude-code-user-config/
• 精简 CLAUDE.md： https://blog.atusy.net/2025/12/17/minimizing-claude-md/
• site2skill：https://github.com/laiso/site2skill

15. 权限系统参考

15.1. 权限模式

模式	说明
default	首次使用每个工具时请求权限
acceptEdits	在本次会话中自动接受文件编辑权限
plan	计划模式：仅分析，不做修改
dontAsk	除非通过允许规则预先批准，否则自动拒绝
bypassPermissions	跳过所有提示（仅在隔离环境中使用）

15.2. 规则评估顺序

规则按以下顺序评估：deny -> ask -> allow。第一个匹配的规则优先。

15.3. Bash 通配符模式

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": ["Bash(git push *)"]
  }
}

注意：* 前的空格很重要：Bash(ls *) 会匹配 ls -la，但不会匹配 lsof。

15.4. 读取/编辑路径模式

模式	含义	示例
//path	从根目录开始的绝对路径	Read(//Users/alice/**)
~/path	从主目录开始的路径	Read(~/.zshrc)
/path	相对于设置文件的路径	Edit(/src/**/*.ts)
path	相对于当前目录的路径	Read(*.env)

注意：* 匹配单个目录，** 递归匹配。

15.5. MCP 和任务权限

{
  "permissions": {
    "allow": ["mcp__puppeteer__*"],
    "deny": ["Task(Explore)"]
  }
}

15.6. 托管设置位置

平台	路径
macOS	/Library/Application Support/ClaudeCode/managed-settings.json
Linux/WSL	/etc/claude-code/managed-settings.json
Windows	C:\Program Files\ClaudeCode\managed-settings.json

15.7. 仅限托管的设置

设置	说明
disableBypassPermissionsMode	设置为 "disable" 以禁止绕过模式
allowManagedPermissionRulesOnly	仅应用托管规则
allowManagedHooksOnly	仅允许托管/SDK 钩子

16. 基于洞察的建议

根据使用情况分析（55K 条消息，4.7K 个会话）：

16.1. 已应用

• DB 操作的架构验证：参见 databricks 技能第 8 节

16.2. 未应用

• 完成状态报告：没有使用此输出的使用方
• SQL 的 PreToolUse 钩子：改由技能指南处理

17. 参考资料

• 钩子参考：https://code.claude.com/docs/en/hooks
• 权限参考：https://code.claude.com/docs/en/permissions
• 技能动态上下文： https://code.claude.com/docs/en/skills#inject-dynamic-context
• Vercel AGENTS.md 指南：https://vercel.com/blog/agents-md