AI Agent 的 Harness 设计哲学

while (true) {                              // ← 无限循环。就这么简单。

  // 1. 调用 Claude API
  for await (const message of deps.callModel({
    messages: messagesForQuery,
    systemPrompt: fullSystemPrompt,
    tools: toolUseContext.options.tools,
    toolChoice: undefined,                   // ← 模型自由选择工具
  })) {
    // 收集流式响应 + tool_use blocks
  }

  // 2. 是否需要继续？
  if (!needsFollowUp) {
    break                                    // ← 自然结束
  }

  // 3. 执行工具，把结果喂回去
  yield* runTools(toolUseBlocks, ...)
  // 循环回到步骤 1
}

// getUsingYourToolsSection() — 工具使用优先级
"Do NOT use Bash to run commands when a relevant dedicated tool is provided.
 This is CRITICAL to assisting the user:
 - To read files use Read instead of cat, head, tail, or sed
 - To edit files use Edit instead of sed or awk
 - To create files use Write instead of cat with heredoc
 - To search for files use Glob instead of find or ls
 - To search content use Grep instead of grep or rg"

// getSimpleDoingTasksSection() — 代码质量规范
"Don't add features, refactor code, or make 'improvements' beyond what was asked."
"Don't add error handling for scenarios that can't happen."
"Don't create helpers or abstractions for one-time operations."
"Three similar lines of code is better than a premature abstraction."

// GlobTool 的 description —— 不只说「能做什么」，还说「什么时候用别的工具」
"- Fast file pattern matching tool that works with any codebase size
 - When you are doing an open ended search that may require multiple
   rounds of globbing and grepping, use the Agent tool instead"

// BashTool 的 description —— 嵌入了大量使用指南
"- Avoid unnecessary sleep commands
 - Do not retry failing commands in a sleep loop — diagnose the root cause
 - If you must poll an external process, use a check command rather than sleeping first
 - NEVER skip hooks (--no-verify) unless the user explicitly asks"

for await (const message of deps.callModel({
  messages: messagesForQuery,
  systemPrompt: fullSystemPrompt,
  tools: toolUseContext.options.tools,
  toolChoice: undefined,    // ← 不强制任何工具。模型自己选。
})) { ... }

/**
 * Shipped because Claude was burning turns on `ls`/`mkdir -p` before writing.
 * Harness guarantees the directory exists via ensureMemoryDirExists().
 */
export const DIR_EXISTS_GUIDANCE =
  'This directory already exists — write to it directly with the Write tool
   (do not run mkdir or check for its existence).'

// System Prompt 明确告知模型 Harness 的赋能存在：

"The system will automatically compress prior messages in your conversation
 as it approaches context limits. This means your conversation with the user
 is not limited by the context window."

"Calling Agent without a subagent_type creates a fork, which runs in the
 background and keeps its tool output out of your context — so you can keep
 chatting with the user while it works."

const VERIFICATION_SYSTEM_PROMPT = `You are a verification specialist.
Your job is not to confirm the implementation works — it's to try to break it.

You have two documented failure patterns:

First, verification avoidance: when faced with a check, you find reasons
not to run it...

Second, being seduced by the first 80%: you see a polished UI or a
passing test suite and feel inclined to pass it, not noticing half the
buttons do nothing...

Your entire value is in finding the last 20%.`

// Hook 返回 preventContinuation = true → 模型被阻止继续
if (result.preventContinuation) {
  stopReason = result.stopReason || 'Stop hook prevented continuation'
}

// 标记 1：模型过度注释问题
// @[MODEL LAUNCH]: Update comment writing for Capybara —
// remove or soften once the model stops over-commenting by default

// 标记 2：模型不够彻底问题
// @[MODEL LAUNCH]: capy v8 thoroughness counterweight —
// un-gate once validated on external via A/B

// 标记 3：模型虚假声明问题
// @[MODEL LAUNCH]: False-claims mitigation for Capybara v8
// (29-30% FC rate vs v4's 16.7%)

// 正常模式：700+ 行精心编排的 System Prompt
return [
  getSimpleIntroSection(),        // 身份 + 风格
  getSimpleSystemSection(),       // 系统规则
  getActionsSection(),            // 安全准则
  getUsingYourToolsSection(),     // 工具使用
  getSimpleToneAndStyleSection(), // 输出风格
  getOutputEfficiencySection(),   // 效率
  ...resolvedDynamicSections,     // 记忆 + 环境
]

// SIMPLE 消融模式：一行字符串
if (isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) {
  return [`You are Claude Code, Anthropic's official CLI for Claude.
CWD: ${getCwd()}
Date: ${getSessionStartDate()}`]
}

// 这些文件被保护不是因为模型「不可信」
// 而是因为 Prompt Injection 可以绕过模型的判断
export const DANGEROUS_FILES = [
  '.bashrc',       // Shell 启动 → 命令注入载体
  '.gitconfig',    // Git 配置 → 可嵌入恶意 Hook
  '.ssh/config',   // SSH → 凭据泄露风险
]

// Harness 内部路径则自动放行 — 因为内容由 Harness 控制
// "this subtree is harness-controlled"
if (normalizedPath.startsWith(bundledSkillsRoot)) {
  return { behavior: 'allow' }  // ← 信任 Harness 管控的路径
}

// Harness-science L0 ablation baseline.
// feature() gate DCEs this entire block from external builds.
if (feature('ABLATION_BASELINE') &&
    process.env.CLAUDE_CODE_ABLATION_BASELINE) {
  for (const k of [
    'CLAUDE_CODE_SIMPLE',                    // System Prompt → 1行
    'CLAUDE_CODE_DISABLE_THINKING',           // 关闭 Thinking
    'DISABLE_INTERLEAVED_THINKING',           // 关闭交错思维
    'DISABLE_COMPACT',                       // 关闭压缩
    'DISABLE_AUTO_COMPACT',                   // 关闭自动压缩
    'CLAUDE_CODE_DISABLE_AUTO_MEMORY',        // 关闭记忆
    'CLAUDE_CODE_DISABLE_BACKGROUND_TASKS',   // 关闭后台
  ]) {
    process.env[k] ??= '1'
  }
}