使用 Home Manager 声明式配置 Claude Code 自定义 Agent以代码审查 Agent 为例【免费下载链接】home-managerManage a user environment using Nix [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager导读本文围绕 Home Manager 中programs.claude-code.agents选项的测试样例文件 expected-code-reviewer.md 展开讲解如何用 Nix 声明式地定义 Claude Code 的自定义 Agentagent并将其写入~/.claude/agents/目录。读完本文你将掌握 Agent 文件的 Markdown 结构与 frontmatter 语法、在home.nix中通过内联字符串或文件路径两种方式声明 Agent、以及如何通过 Home Manager 的测试体系验证生成结果。一、目标文件解读一个代码审查 Agent 的完整形态关联文档 expected-code-reviewer.md 是 Home Manager 针对programs.claude-code模块的测试预期输出文件它描述了一个名为code-reviewer的代码审查 Agent。文件本身是一份标准的 Claude Code Agent 定义由两部分组成1. frontmatterYAML 元数据头--- name: code-reviewer description: Specialized code review agent tools: Read, Edit, Grep ---nameAgent 的标识名与文件名code-reviewer.md保持一致在 Claude Code 中通过/code-reviewer之类的斜杠命令唤起description一句话描述用于说明该 Agent 的职责帮助模型在合适的场景下选用它tools允许该 Agent 使用的工具白名单这里是Read, Edit, Grep即只授予读取、编辑与搜索能力刻意不开放 Bash 等高风险工具符合代码审查场景只读 定点修改的权限边界。2. 系统提示词正文You are a senior software engineer specializing in code reviews. Focus on code quality, security, and maintainability.frontmatter 之后是 Agent 的系统提示词定义了角色定位资深软件工程师与审查关注点代码质量、安全性、可维护性。这部分是 Agent 行为的核心指令会被注入到模型上下文中。二、这份文件从哪里来agents 选项的生成链路expected-code-reviewer.md并不是手写的独立文件而是 Home Manager 的programs.claude-code.agents选项在测试中被渲染后的预期结果。在 full-config.nix 中可以看到它对应的声明agents { code-reviewer --- name: code-reviewer description: Specialized code review agent tools: Read, Edit, Grep --- You are a senior software engineer specializing in code reviews. Focus on code quality, security, and maintainability. ; };生成链路的底层实现在 default.nix 与 lib.nix 中agents选项的定义位于 options.nixmkContentOption将类型声明为attrsOf (either lines path)即每个属性值既可以是内联多行字符串也可以是一个指向文件的路径在配置阶段default.nix 调用mkMarkdownEntries agents cfg.agents把每个属性对映射为${configDir}/agents/${name}.md文件mkMarkdownEntries实现在 lib.nix根据值是路径还是字符串分别生成source符号链接或text文本写入两种home.file条目。默认configDir为~/.claude见 options.nix因此上述声明最终生成~/.claude/agents/code-reviewer.md内容与预期文件逐字节一致。三、两种声明方式内联字符串与文件路径agents选项的每个值支持两种形态方式一内联多行字符串直接在 Nix 配置中书写 frontmatter 与提示词适合内容较短的 Agentprograms.claude-code { enable true; agents { code-reviewer --- name: code-reviewer description: Specialized code review agent tools: Read, Edit, Grep --- You are a senior software engineer specializing in code reviews. Focus on code quality, security, and maintainability. ; }; };方式二引用文件路径将 Agent 内容维护在仓库中的独立 Markdown 文件里适合内容较长、需要独立版本管理的场景agents { documentation ./agents/documentation.md; };该方式的实际效果由测试 agents-path.nix 验证test-agent.md作为路径被写入~/.claude/agents/test-agent.md测试断言文件内容与原文件一致。与 agentsDir 的取舍如果 Agent 文件已经成规模地存在于某个目录中也可以使用agentsDir选项见 options.nix把整个目录递归符号链接进agents/子目录。需要注意default.nix 中的断言规定agents与agentsDir不可同时设置二者是互斥关系。agentsDir的目录级链接行为由测试 agents-dir.nix 覆盖其中assertLinkExists确认生成的是符号链接而非复制。四、验证机制测试如何保证生成结果正确Home Manager 对agents选项的验证采用 Nix module testnmt框架。在 full-config.nix 中测试断言assertFileExists home-files/.claude/agents/code-reviewer.md assertFileContent home-files/.claude/agents/code-reviewer.md ${./expected-code-reviewer.md}即code-reviewer.md文件必须存在且内容必须与 expected-code-reviewer.md 完全一致。这类预期输出文件 逐字节比对的测试模式保证了用户无论以何种方式声明 Agent最终落盘的配置都严格可预期、可复现——这正是声明式配置的核心价值。另外basic.nix测试basic.nix验证了未启用模块或未配置 agents 时不生成~/.claude目录避免空目录污染用户环境。五、Agent 之外与 commands、hooks、rules 的组合运用Agent 只是 Claude Code 模块提供的自定义能力之一。围绕同一个configDiroptions.nix 还定义了同构的配置项均可与agents组合使用构成完整的开发工作流选项落盘位置典型用途settings~/.claude/settings.json权限、主题、hooks、statusLine 等 JSON 配置commands~/.claude/commands/*.md斜杠命令如 git commit 模板hooks~/.claude/hooks/*可执行事件钩子脚本如 pre-edit、post-commitrules~/.claude/rules/*.md模块化规则文件自动作为项目记忆加载skills~/.claude/skills/name/SKILL.md自定义技能context~/.claude/CLAUDE.md全局上下文例如在 full-config.nix 中hooks以可执行脚本形式写入~/.claude/hooks/并通过assertFileIsExecutable验证权限位commands与agents使用同一套mkMarkdownEntries机制因此生成与校验逻辑完全一致。六、上手步骤在 Home Manager 中启用要在自己的配置中启用这一能力只需在home.nix或对应的 NixOS / nix-darwin 模块中加入{ config, pkgs, ... }: { programs.claude-code { enable true; agents { code-reviewer --- name: code-reviewer description: Specialized code review agent tools: Read, Edit, Grep --- You are a senior software engineer specializing in code reviews. Focus on code quality, security, and maintainability. ; }; }; }随后执行home-manager switch完成切换。生成后可在~/.claude/agents/code-reviewer.md检查落盘结果。若自定义了configDir例如改为${config.xdg.configHome}/claudedefault.nix 会自动导出CLAUDE_CONFIG_DIR环境变量确保 CLI 从同一位置读取配置。结语expected-code-reviewer.md虽然只有短短数行却完整示范了 Claude Code Agent 的最小可用定义frontmatter 声明身份与工具权限正文承载角色与行为指令。在 Home Manager 中它以programs.claude-code.agents选项为入口经过 lib.nix 的渲染逻辑落到~/.claude/agents/目录并有完整的 nmt 测试full-config.nix、agents-path.nix、agents-dir.nix保证其可复现性。参考这一模式你可以把评审、文档、测试编写等各类专业 Agent 全部纳入声明式配置随home-manager switch一键部署。【免费下载链接】home-managerManage a user environment using Nix [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考