企业官网建设流程全解析

Claude Code Harness 配置文件速览：claude-code-harness.config.json 关键参数详解

【免费下载链接】claude-code-harnessClaude Code Dedicated Development Harness - Achieving High-Quality Development Through an Autonomous Plan→Work→Review Cycle项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-harness

面向新手和普通用户的完整指南，带你看懂 Claude Code Harness 的安全与行为配置。

一、30 秒认识这份配置文件

Claude Code Harness是一套为 Claude Code 打造的「自动驾驶开发框架」，通过自动的Plan → Work → Review循环来保证开发质量。而控制它"油门和刹车"的，就是项目根目录下的claude-code-harness.config.json配置文件。

这份配置文件决定了 AI 能自动提交吗？能自动 push 吗？哪些目录绝对不能碰？失败后重试几次？——所有关乎安全边界的关键开关，都在这里。

在项目中，你可以直接查看两个关键文件：

• 官方示例配置：claude-code-harness.config.example.json
• 参数结构定义（Schema）：claude-code-harness.config.schema.json

💡 小技巧：把 schema 文件的$schema地址指给你的编辑器，即可获得 JSON 自动补全和实时校验，新手配置也不易写错。

二、配置速览：一张表看懂 8 大模块

三、核心参数逐个讲（新手必看）

1.safety.mode：最关键的三档安全开关

这是整个配置文件里最重要的参数，决定 AI 操作的根本力度：

• dry-run（演练模式）：只展示"我会做什么"，不真正执行。新手强烈建议从这里开始。
• apply-local（本地执行）：真正修改本地文件，但不会 push 到远程。
• apply-and-push（全自动）：完整自动化，需显式启用，适合成熟团队。

配套的两个参数：

• require_confirmation: true：破坏性操作前必须人工确认（默认开启，别关）；
• max_auto_retries: 3：失败后最多自动重试 3 次，超过就升级上报给人。

2.git：自动提交与推送的边界

"git": { "allow_auto_commit": false, "allow_auto_push": false, "protected_branches": ["main", "master", "production"], "commit_prefix": "fix:" }

• allow_auto_push依赖allow_auto_commit，两者默认都是false——默认不自动提交、不自动推送；
• protected_branches是"永禁自动 push"的分支名单，main、master、production是默认值；
• commit_prefix控制自动生成提交信息的消息前缀（如fix:）。

3.paths：给文件操作画一条"围栏"

这是防 AI"乱动文件"的核心：

• allowed_modify：允许修改的白名单，如src/、lib/、Plans.md；
• protected：永远不碰的黑名单，如.github/、terraform/、.env、secrets/；
• plans_file/agents_file：指定任务文件（Plans.md）和代理配置文件（AGENTS.md）的位置。

🛡️ 提示：官方甚至把配置文件本身也加入了写入保护范围，防止 AI 通过改配置绕过安全策略，这一设计思路在 CHANGELOG.md 中有详细记录。

4.destructive_commands：破坏性命令的保险丝

max_files_to_modify: 20是个很实用的护栏——防止 AI 一次改 200 个文件让你无从回滚。

5.ci：接入你的持续集成

• provider：可选github_actions、gitlab_ci、circleci、none或auto（自动从项目配置中检测，默认）；
• enable_auto_fix：CI 报错时自动尝试修复，默认关闭（官方标注为危险项）；
• require_gh_cli：使用 GitHub Actions 时要求安装gh命令行工具。

6.scaffolding：技术选型的三种姿势

tech_choice_mode决定 AI 帮你搭项目时怎么选技术栈：

• ask（默认）：每次都问你，最稳妥；
• auto：AI 自行决定；
• fixed：锁定预设栈（通过base_stack指定，如next-supabase）。

allow_web_search: true则允许 AI 联网搜索最新的技术推荐。

7.runtimefloor：密钥读取的"硬地板"

secretAllow用于预先声明允许读取哪些本地密钥文件：

"runtimefloor": { "secretAllow": [".env.local", "secrets/pipeline.key"] }

注意它的严格规则：相对路径必须在项目根目录内解析，项目外的绝对路径一律无效——这是为了防止通过../../etc/shadow这类路径穿越绕过安全底线。

8. 其他实用参数

• work.auto_commit（默认true）：Review 通过后自动提交；
• work.commit_on_pm_approve：双 Agent 模式下，等 PM 批准后再提交（true时延后提交）；
• i18n.language：en或ja，控制命令与提示信息的显示语言，读取逻辑见 scripts/config-utils.sh；
• constitution.path：指向"项目宪法"文件（默认docs/constitution.md），集中定义质量门禁与完成标准。

四、上手建议：新手配置三步走 🚀

1. 复制示例：以 claude-code-harness.config.example.json 为起点，改名为claude-code-harness.config.json放到项目根目录；
2. 保守起步：保持safety.mode: "dry-run"+require_confirmation: true，先观察 AI 的计划动作，熟悉后再切到apply-local；
3. 收紧边界：把生产相关目录（infra/、terraform/、secrets/）确认列入protected，把日常代码目录列入allowed_modify。

五、写在最后

claude-code-harness.config.json就像 Claude Code Harness 的"安全仪表盘"：safety管油门，paths和protected_branches管车道，destructive_commands管急刹。理解了这几组关键参数，你就能在"让 AI 多干活"和"守住安全底线"之间找到最适合自己的平衡点。

想深入了解各参数的演化历史与修复细节，可以翻阅仓库中的 CHANGELOG.md 与 spec.md，它们记录了每一次配置行为的变更来龙去脉。

【免费下载链接】claude-code-harnessClaude Code Dedicated Development Harness - Achieving High-Quality Development Through an Autonomous Plan→Work→Review Cycle项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-harness