前两章讲了骨架与零件四阶段流水线、七角色博弈、十个核心概念。这一章把镜头对准地基——Harness 工程在磁盘上的布局。每个文件该放哪、该被谁读、该解决什么问题在目录层面就已定型。不懂目录你就无法判断哪个文件是权威、哪个文件会被机器校验、哪个文件改了会触发什么。4.1.harness/与.claude/两套目录各司其事打开 Harness 工程的根目录你会看到两大配置目录并排.harness/和.claude/。这两个名字容易让人以为它们是一回事但它们的职责有严格分工.harness/——Harness 的数据与机器放状态、契约、知识、脚本。这是 Harness 框架自己管理的东西——系统能力真相specs/、经验库memory/、任务看板tasks/、角色契约workflow/、自动化脚本scripts/、脚手架模板templates/。.它回答系统现在知道什么、机器接下来要做什么。.claude/——Claude Code 的身份与行为放角色定义、命令、规则、技能、钩子。这是 Claude Code 原生消费的配置——Agent 该如何行事agents/、用户如何触发commands/、不可碰的红线rules/、标准操作手册skills/、实时拦截hooks/。它回答AI 是谁、它该怎么行动。一句话概括两者的分工.harness/是记忆与机器.claude/是身份与规则。前者存系统知道什么后者存AI 怎么做。下面这张目录树来自一个真实的 Harness 工程我用它来实地讲解每个目录的职责请对照这张树记住三个关键观察观察点一目录结构本身就是四层元模型第 3 章的物理映射。你看——workflow/和config.json是契约层agents/、commands/、skills/是行为层specs/、memory/、codebase-guide/是知识层scripts/、hooks/、rules/、tasks/是执行层。四层元模型不是抽象概念你打开目录就能看到。理解了四层你就知道任何一个文件该去哪、该怎么归类。观察点二.harness/agents/是指向.claude/agents/的符号链接。同一个角色定义只有一个权威源在.claude/.harness/agents/只是提供一条更符合框架心智的访问路径。这体现了单一真相源在文件系统层面的一种常见手法用链接而不是副本——复制会制造双份真相链接不会。观察点三deliverables/的活目录 归档设计。在途任务用deliverables/task/归档后用_archive/task/活目录定期清空、归档目录增量追加。这套设计我在第 10 章Archive会完整展开这里你先种个印象Harness 把进行中与已沉淀在磁盘上就分开了。settings.jsonHook 是怎么被注册的有一个文件值得单独看一眼——.claude/settings.json。它就是第 3 章讲的三个 Hook 的注册表Claude Code 通过它知道哪个事件触发哪个脚本。{hooks:{PreToolUse:[{matcher:Edit|Write,hooks:[{type:command,command:python3 .claude/hooks/pre_edit.py}]}],UserPromptSubmit:[{matcher:,hooks:[{type:command,command:python3 .claude/hooks/pre_command.py}]}],PostToolUse:[{matcher:Agent,hooks:[{type:command,command:python3 .claude/hooks/dev_gate.py}]}]}}注意三个 Hook 的触发设计每个都精心选择了时机和匹配范围这就是纵深防御在配置层面的形态同一个规则如分支合规不靠一个检查点守住而是靠多个 Hook、多个时机独立 enforce。细节在第 9 章展开。4.2config.json——全局兜底配置与单一真相源的入口在 4.1 的目录树里我特意给config.json标了 ★。它只有几行却是整个 Harness 最容易被误用的地方——也是最容易被硬编码毁掉的地方。先看它的真实内容{apply-mode:review,mainline-branch:dev,description:Apply 流程模式: autoCR 通过后自动进入 TE(默认); reviewCR 通过后暂停等待人工审查通过后再进入 TE。任务级可用 proposal.md 的 flow-mode 字段覆盖。mainline-branch: 子工程主线分支集成/同步/归档合并目标子工程 .harness/build.json 的 mainline-branch 字段可覆盖默认 dev。}只有两个真正的配置项我来逐一讲它们的设计意图mainline-branch把主线分支名从代码里拔出来想象一下没有这个配置的 Harness 会怎样sync.py要同步到哪个分支create_feat_branch.py从哪个分支建特性分支archive.py要把 feat 分支合并到哪verify.py检查是否在集成分支要看哪几个分支名所有这些脚本的答案原本只能靠硬编码。而在一个演进中的工程里主线分支叫 dev 还是 develop 还是 release-2.x是会变的。如果你把dev写死在 18 个脚本里改一次主线分支名 改 18 处 祈祷没漏。Harness 的做法是把这条信息收敛到一处config.json并设计了一套三级覆盖优先级大多数子工程不配置 → 用根 config.json 的dev某个子工程特殊比如单独维护的 legacy 仓库用release-x→ 在自己 build.json 里覆盖都没有 → 兜底默认dev。而所有脚本sync / create_feat_branch / check_branch / verify / archive都通过lib.py里唯一的get_mainline_branch(service_path)函数读取这个值——全世界只有一个地方知道主线分支叫什么。这就是单一真相源不是不要硬编码而是把硬编码收敛到一个地方再让所有人读它。apply-mode把流程行为收敛到配置文件第二个配置项apply-mode控制的是 Apply 阶段的流程行为这个我在第 2 章 2.4 已经接触过apply-mode: auto → CR 审查通过后自动进入 TE apply-mode: review → CR 审查通过后暂停等待人工审查 code-review.md人确认后再进 TE注意它的优先级设计与 mainline-branch 同思路proposal.md 的 flow-mode任务级 .harness/config.json 的 apply-mode全局 默认 auto这样设计的好处流程行为这个本该人人皆知、处处一致的东西有了一个权威来源。单任务特例proposal 里写flow-mode: review不会破坏全局全局改档config.json 改auto不用逐个任务改。配置项的每一层决策都发生在离决策最近的地方——这是配置设计的黄金法则。一句话理解 config.jsonconfig.json每个被放进这里的配置项都回答同一个问题“这个值全系统都应该一致地知道但它不藏在任何一个具体脚本里。” 当你发现某个值被 3 个以上脚本硬编码时它就该被提升到 config.json。4.3 跨平台兼容层macOS 与 Windows 的双系统纪律最后一块地基是跨平台兼容。你可能觉得这没什么好讲的——“脚本写好不就行了”——但 Harness 面对的是一个极其刺眼的现实团队里一半人用 macOS一半人用 Windows。macOS 开发者习惯了bash -lc、which、export PATH、eval $(...)Windows 开发者面对的是cmd、where、set、PowerShell 的$env:路径分隔符一个/一个\行尾一个 LF 一个 CRLF删文件一个rm -rf一个rmdir /s /q。如果 Harness 的脚本是单平台写的团队里必然有一半人每天的开工仪式是先折腾环境。Harness 用一整套设计把这件事制度化核心是os-compatibility.md规则文件 check_harness.py的跨平台扫描。os-compatibility.md写成法律的兼容纪律Harness 把跨平台要求写成了强制规则.claude/rules/os-compatibility.md。注意它的措辞——不是尽量兼容而是违反 → check_harness.py 跨平台扫描 FAIL。我摘几条最硬的规定条款禁止强制Python 子进程调用硬编码python3/python作为 program用sys.executable命令执行os.system、shellTruesubprocess/lib.runlist 形式文件删除rm -rf/rm -r/rmdirPython 内shutil.rmtree/Path.unlink脚本形态.harness/下新增.sh除 git-hooks/跨平台脚本一律 Python行尾CRLF框架脚本与 git hook 必须 LFhook shebang#!/bin/sh python3/python 兜底为什么这些条目能上法律因为每一条都对应着一个真实事故硬编码python3在 Windows 上不存在是python.exeos.system无法跨平台rm -rf在 Windows 上会直接报错CRLF 行尾会让 shebang 失效。这些事故足够痛才值得写成 FAIL 级规则。check_harness.py的跨平台扫描机器来执法光有规则文件不够——AI 可能看不见规则人可能忘执行它。所以check_harness.py全量校验里内置了一个「️ 跨平台兼容」检查段用正则扫描的方式自动执法。让我把真实工程的执行结果展示给你看️ Harness 系统完整性检查 ... 三边一致性校验... ✅ contract.json role [PM] ↔ project-manager.md ✅ contract.json role [BA] ↔ business-analyst.md ✅ contract.json role [SA] ↔ solution-architect.md ✅ contract.json role [RR] ↔ readiness-reviewer.md ✅ contract.json role [Dev] ↔ developer.md ✅ contract.json role [CR] ↔ code-reviewer.md ✅ contract.json role [TE] ↔ test-engineer.md ️ 跨平台兼容检查macOS Windows ✅ 跨平台扫描0 ERROR / 0 WARNING通过 PASS: 66 FAIL: 0 ✅ 框架完整性检查全部通过这条规则是双重的它强制框架本身跨平台scripts/hooks 的代码风格也强制写文档的人别忘了给 Windows 留口子——例如os-compatibility.md明确要求命令文档里若含rm -rf等 POSIX 专属命令必须注明 Windows 等价写法rmdir /s /q/Remove-Item -Recurse -Force。文档也是兼容层的一部分。env_auto.py跨平台兼容的实战代表跨平台纪律不是为兼容而兼容——它服务于一个真实的强需求零配置环境自动识别第 7 章会完整展开。这里我先看它跨平台的一面。env_auto.py站在每个子工程面前自动回答三个问题这是什么工程需要什么版本这台机器上哪个运行时满足真实输出长这样macOS$ python3 .harness/scripts/env_auto.py services/backend ✅ Java 1.8 → /Library/Java/JavaVirtualMachines/jdk1.8.0_191.jdk/Contents/Home ✅ Node 14 → /opt/homebrew/bin backend: Java 1.8、Node 14 — ✅ 环境就绪 [formatposix] export JAVA_HOME/Library/Java/JavaVirtualMachines/jdk1.8.0_191.jdk/Contents/Home export PATH/Library/Java/JavaVirtualMachines/jdk1.8.0_191.jdk/Contents/Home/bin:$PATH export PATH/opt/homebrew/bin:$PATHservices/frontend就更薄——一个纯前端工程只需要 Node$ python3 .harness/scripts/env_auto.py services/frontend ✅ Node 14 → /opt/homebrew/bin frontend: Node 14 — ✅ 环境就绪 [formatposix] export PATH/opt/homebrew/bin:$PATH注意输出的最后一行export语句本身就是跨平台兼容的产物。export是 POSIX 语法macOS/Linux而 Windows 上是另一套。env_auto.py支持三种输出格式按平台自动切换同样一份探测逻辑三种 shell 各出一套加载语法——跨平台的本质不是写一套哪里都能跑的代码而是把平台差异隔离在输出层让上层逻辑完全一致。这就是为什么os-compatibility.md要求新增 shell 输出型脚本时参考 env_auto.py 的detect_format/fmt_exports实现——它成了跨平台输出层的标杆实现。跨平台兼容的三层防线总结这三层分别解决了意识的约束、“执行的约束”、“设计的约束”——规则管想法、扫描管动作、模式管结构。小结这一章我带你看了 Harness 的地基两套目录——.harness/存系统知道什么数据机器.claude/存AI 怎么做身份规则目录结构本身就是四层元模型的物理映射config.json——把主线分支名流程模式这类全局共识收敛到一处用三级覆盖优先级让单一真相源落地跨平台兼容层——os-compatibility.md规则 check_harness.py机器扫描 env_auto.py输出层模式三层防线让 macOS/Windows 双平台团队共享同一套流程settings.json / templates/ git-hooks/——Hook 注册表、脚手架弹药库、提交门禁入口各司其职。下一章走进这层地基里最重要的一根承重柱——Spec 系统为什么系统能力需要一个单一真相源GWT 格式为什么是防 AI 作弊的物理锁跨域机制 FLOW 与 CSTR 如何不复制行为地编排全局翻到第 5 章。