Claude Code 工程化实战第 7 讲：可写型子代理的 permission 与 Edit/Write 配置骨架

1. 可写型子代理为什么最容易翻车Claude Code 的子代理体系里只读型Read/Grep/Glob和可执行型Bash 白名单都不会改变项目状态跑错了重跑一次就行。可写型子代理是第一个真正会改文件的类别——Edit 和 Write 工具一旦放开AI 就能直接修改源码、覆盖配置、误删测试。写错了不是重跑一下能解决的得 git revert 甚至手工修复。我在实际项目里踩过的坑是给子代理开了 Edit/Write 但没配 permission 的 ask 机制结果它一次性改了 8 个文件弹窗弹了 8 次我嫌烦全点了放行事后发现其中一个改动把src/billing/下的金额计算逻辑改错了。这就是批量写的典型风险——diff 太多人根本 review 不过来。所以可写型子代理的落地核心不是能不能写而是写到哪、写多少、谁来批。这篇聚焦三件事在settings.json里为子代理声明 permission 白名单、开放 Edit/Write 并限定目录、通过统一 Key/API 通道接入后触发一次真实写入并核对结果。适合已经在用 Claude Code 做工程化、准备把子代理从只读升级到可写的开发者。2. 前置统一 Key/API 通道与子代理目录在配 permission 之前先确认两件事模型通道和子代理文件位置。模型通道方面我用的是 TaoToken 的统一接入方式一个 Key 走所有模型不用为每个子代理单独配 endpoint。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个不加 UTM。拿到 Key 后在环境变量里设好export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key子代理文件放在项目的.claude/agents/目录下每个子代理一个.md文件frontmatter 里声明 name、description、tools、model。permission 则统一写在.claude/settings.json里按工具名分组用file_path正则做目录级限定。注意permission 是工具层的硬约束子代理 system prompt 里的我只写 docs/是软约束。软约束会被 AI 的顺手优化绕过硬约束不会。两层都要有。3. 可复制的 settings.json 骨架下面这份骨架是我在多个项目里验证过的直接改路径就能用。核心思路是三层deny 绝对禁止、ask 写前弹窗、allow 文档安全区。{ permissions: { Edit: [ {file_path: migrations/.*, permission: deny}, {file_path: .*\\.env.*, permission: deny}, {file_path: .*secret.*, permission: deny}, {file_path: .*credential.*, permission: deny}, {file_path: src/billing/.*, permission: deny}, {file_path: src/.*\\.py, permission: ask}, {file_path: tests/.*\\.py, permission: ask}, {file_path: config/.*, permission: ask}, {file_path: docs/.*\\.md, permission: allow}, {file_path: README\\.md, permission: allow}, {file_path: CHANGELOG\\.md, permission: allow}, {file_path: .claude/drafts/.*, permission: allow} ], Write: [ {file_path: migrations/.*, permission: deny}, {file_path: .*\\.env.*, permission: deny}, {file_path: src/.*, permission: ask}, {file_path: docs/.*\\.md, permission: allow}, {file_path: .claude/drafts/.*, permission: allow} ] }, limits: { Edit: { max_files_per_call: 3, max_diff_lines_per_call: 200, warn_above_files: 5 } } }几个关键点解释一下。Edit 和 Write 分开配因为 Write 只应该创建新文件如果目标已存在就该拒绝并提示改用 Edit。src/billing/配 deny 是因为金额相关代码写错代价太高宁可让 AI 报无权限也不要它碰。limits里的max_files_per_call: 3是防批量写的关键——超过 3 个文件触发额外警告逼你更仔细地 review。子代理的 frontmatter 里 tools 要显式声明 Edit 和 Write否则即使 permission 配了也不会生效--- name: doc-writer description: Update README, generate API docs from docstrings. Use when I say 更新文档. tools: Read, Grep, Glob, Edit, Write model: haiku ---4. 验证触发一次写入并核对结果配好之后必须做一次真实写入验证光看配置不算数。我用的验证动作是让 doc-writer 更新 README 的版本号。第一步在项目里对 Claude Code 说用 doc-writer 把 README 里的版本号从 1.2.3 更新到 1.3.0。预期行为是子代理读取package.json拿到新版本号然后对README.md发起 Edit。第二步观察弹窗。因为README.md配的是 allow理论上不该弹窗。如果弹了说明你的 permission 正则没匹配上——检查是不是写成了README.md而实际路径带前缀。第三步核对文件变更git diff README.md应该只看到版本号那一行变化。如果 diff 里出现了src/下的改动说明子代理角色漂移了需要回到 system prompt 里加硬边界。第四步测试拦截。故意让子代理改src/billing/amount.py预期是直接被 deny 拦下报无权限修改该路径。如果它成功改了说明 deny 规则没生效检查正则里的转义——src/billing/.*里的点号要写成\\.。第五步测试 ask 机制。让子代理改src/utils/helper.py预期弹窗展示想改什么、改到哪、改了几行。这时候你可以选放行、拒绝或编辑后再放行。这一步验证的是逐次审批是否真的在工作。5. 本篇常见错排查错误一给了 Edit/Write 但没配 ask等于让 AI 自由改代码。最隐蔽的坑是 frontmatter 写了tools: Edit, Writesettings.json 里也配了 permission但 Edit 的 permission 写成了 allow 而不是 ask。结果 AI 能自由改任何文件。判断标准可写子代理的 Edit/Write 必须配 ask且 file_path 维度要有 deny 兜底。只有 allow 没有 ask立即停用。错误二批量写的风险被低估。permission 配了 ask 但没配max_files_per_callAI 一次 Edit 10 个文件弹窗弹 10 次用户嫌烦全放行ask 形同虚设。解决就是在 limits 里加文件数和 diff 行数限制超过阈值触发额外警告。错误三角色漂移写文档时顺手改了源码。用户说用 doc-writer 更新 README它跑着跑着顺手优化了src/里的 import 顺序。修正方式是在 system prompt 里写死硬边界白名单 黑名单同时 permission 对src/配 deny 而不是 ask——AI 看到 deny 触发我无权限角色漂移被工具层堵死。错误四没有 Audit 日志写错了不知道谁改的。出事故时发现某文件被改但不知道是 AI 改的还是人改的、什么时候改的。解决是在 PostToolUse Hook 里配 audit 记录每次 Edit/Write 都写一条到.claude/audit.log不进 git。审计时直接查日志。#!/usr/bin/env bash TOOL_NAME$1 FILE_PATH$2 USER_DECISION$3 TIMESTAMP$(date -Iseconds) if [[ $TOOL_NAME Edit || $TOOL_NAME Write ]]; then echo $TIMESTAMP | $TOOL_NAME | $FILE_PATH | $USER_DECISION .claude/audit.log fi exit 06. 接入通道与后续动作可写型子代理的模型调用走统一 Key 通道一个 Key 覆盖所有子代理不用为每个 agent 单独配 endpoint。如果你还没配好 Key先去 API Keys 页面生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入细节看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。验证阶段想快速试模型对话行为可以用模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你要把可写子代理长期跑在编码流程里建议上 Coding Plan额度更稳https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后补一句实操经验permission 配好之后先拿一个不重要的仓库跑一周观察 audit 日志里 ask 的触发频率和放行率。如果放行率超过 90%说明你的 ask 阈值太松该收紧 file_path 正则了。