Claude Code 是一个跑在终端里的"AI 编程伙伴"。它不是 ChatGPT 那种聊天框，而是一个有工具权限的 agent：能读文件、改文件、跑命令、起子任务。

你和它打交道有两条路：

• 临时对话：直接和它说话，它当场做事；
• 持久配置：通过项目里的 CLAUDE.md、.claude/、AGENTS.md 等文件，让它在所有未来会话里都遵守你的规则。

项目里 Claude 相关文件全景 #

GoldenEyes/
├── CLAUDE.md                        # ★ Claude Code 硬约定文件名
├── AGENTS.md                        # ★ 业内 AGENT 元约定(Codex/各 Agent CLI 通用)
├── ARCHITECTURE.md                  # 本项目自定:架构速查(被 CLAUDE.md 强引用)
│
├── .claude/                         # ★ Claude Code 硬约定目录
│   ├── settings.local.json          # ★ 硬约定文件名(本机私人,gitignored)
│   ├── commands/
│   │   └── goldeneyes-harness.md    # 硬约定:文件名 = slash command 名
│   └── skills/
│       └── goldeneyes-harness-request/
│           ├── SKILL.md             # ★ 硬约定文件名(必须全大写)
│           ├── agents/
│           │   └── claude.yaml      # 本项目自定:UI 展示信息
│           └── references/          # 本项目自定:skill 知识库
│               ├── code-review.md
│               ├── functional-verification.md
│               ├── git-workflow.md
│               ├── problem-decomposition.md
│               ├── research-protocol.md
│               ├── runtime-verification.md
│               ├── stage-checklist.md
│               ├── task-file-contract.md
│               ├── task-observability.md
│               ├── task-routing.md
│               └── uncertainty-gates.md
│
├── .agents/                         # 业内通用约定(Codex CLI 等读)
│   └── skills/
│       └── goldeneyes-harness-request/
│           ├── SKILL.md
│           ├── agents/
│           └── references/          # 与 .claude/.../references 同源副本
│
└── .harness/                        # 本项目自定:工程级事实数据
    ├── project-profile.yaml
    ├── environment.yaml
    ├── workspace-map.yaml
    ├── runtime-topology.yaml
    ├── glossary.yaml
    ├── known-issues.md
    ├── invariants.yaml
    ├── human-gates.yaml
    ├── current-task.json
    ├── tasks/
    └── ...

CLAUDE.md：项目规约（官方约定） #

Claude Code 启动会话时，会自动沿着以下路径读 CLAUDE.md 并把内容塞进系统提示：

官方建议:

• 单文件控制在 ~200 行(超过会增加每次会话的 context 成本)。

• 可以用 @path/to/file 语法导入其他文件(相对/绝对路径都行)。

• settings.json 里有 claudeMdExcludes 字段可排除部分文件。

• 越靠前越重要（系统提示从上往下读）；

• 用祈使句、列表、命令块，少写抒情文字；

AGENTS.md #

【业内通用约定】 AGENTS.md 是 OpenAI Codex CLI 等多家 Agent 工具识别的标准文件,角色与 Claude Code 的 CLAUDE.md 等价。

ARCHITECTURE.md — 架构速查（非官方） #

【本项目自定】 名称不是官方约定,Claude Code 不会自动识别这个文件名。它能进会话上下文,完全是因为 CLAUDE.md 第一段"必读地图"明确点名要求 Claude 在每次任务前读它。

业内有"ARCHITECTURE.md 作为顶层架构文档"的非官方惯例(类似 README.md、CHANGELOG.md),但没有任何工具会自动加载它。要改名(比如 ARCH.md、docs/architecture.md),只需同步更新 CLAUDE.md、AGENTS.md、SKILL.md 里的所有引用即可。

它的作用 #

• 给每个新会话5 分钟内了解仓库轮廓的能力(否则 Claude 必须 ls + glob 才能知道有 14 个子项目)。
• 把"高风险动作"(改 proxy.go、跨 build tag 复用、push 子仓)显式写出来,触发 Claude 的不确定性闸门。
• 列出生成产物让 Claude 跳过不读不改。

.claude #

settings.local.json — 本机权限白名单 #

【Claude Code 硬约定】 文件名固定,用途由 Claude Code 决定。完整体系:

格式 #

【Claude Code 硬约定】 顶层是 JSON 对象。Anthropic 官方发布了 JSON Schema,在文件顶部加一行:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  ...
}

IDE 即可获得字段补全和校验。

GoldenEyes 当前 settings.local.json(只用了 permissions) #

{
  "permissions": {
    "allow": [
      "Bash(go build *)",
      "Bash(go vet *)",
      "Bash(gofmt -l master/api/tag.go ...)",
      "Read(//c/Users/tianzhiwei/go/src/**)",
      "Bash(python3 -c ' *)",
      "Bash(pip install *)",
      ...
    ]
  }
}

观察:全是 allow,没有 deny/ask/defaultMode/env/hooks/sandbox 等任何其他字段。gofmt 大部分条目精确到具体文件路径(用户曾经"Always allow"过,Claude Code 把当时的完整命令快照下来了)。包含 Windows 路径,说明只对当前开发机有效。

字段全表(按类别分组) #

下面是 settings.json 完整字段参考。每个字段标注类型 / 默认值 / 作用 / 示例。GoldenEyes 当前只用了第 5 类的 permissions,其他都是潜在可用能力。

4.1 模型与 LLM #

4.2 认证与 API #

4.3 环境变量 #

4.4 文件与内存 #

4.5 权限(GoldenEyes 当前在用) #

Permission 规则语法 #

4.6 沙箱(sandbox)— macOS / Linux / WSL2 #

Windows 注意:GoldenEyes 当前在 Windows 上,sandbox 不适用。要 Linux 容器隔离,在 WSL2 里跑 Claude Code 才能用。

4.7 UI 与显示 #

4.8 Shell 与输入 #

4.9 Git 与提交署名 #

4.10 Hooks #

Hook 单条完整字段(type: "command") #

type: "http" 时改用 url + body(支持 {{event}} {{cwd}} 模板变量)。

4.11 文件与状态定制 #

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "timeout": 2000,
    "async": true
  }
}

或:

{
  "statusLine": {
    "type": "static",
    "content": "[Branch: main] [Model: opus-4-7]"
  }
}

4.12 MCP 服务器开关 #

4.13 更新与版本 #

4.14 其他 #

推荐的团队级 settings.json(参考) #

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-opus-4-7",
  "effortLevel": "high",
  "language": "简体中文",
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(go test:*)",
      "Bash(go vet:*)",
      "Bash(go build:*)",
      "Bash(gofmt -l *)",
      "Bash(gofmt -d *)",
      "Read(.harness/**)",
      "Read(docs/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Read(.env*)",
      "Read(**/secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "claudeMdExcludes": [
    "**/.tmp-gocache/**",
    "**/swagger/**",
    "harness-project-bootstrap/**/CLAUDE.md"
  ],
  "attribution": {
    "commit": "Co-Authored-By: Claude Code <noreply@anthropic.com>"
  }
}

没有对应字段的特性 #

• 登录 token 存储 — 不在 settings.json,Claude Code 内部用安全存储
• 遥测禁用 — 用 env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
• 主题 / 配色 — 没有独立字段,由终端或 outputStyle 间接影响
• Co-Authored-By 署名 — 由 attribution.commit 配置

改动建议 #

• 想给团队共享权限:把规则移到 ./.claude/settings.json 并提交。
• 想跨项目共享:放到 ~/.claude/settings.json。
• 仓库里有专门 skill fewer-permission-prompts 可以扫历史记录自动生成 allowlist。
• 改 settings 文件时优先用 update-config skill,而不是手工编辑。

官方资源 #

• 设置文档:https://code.claude.com/docs/en/settings.md
• JSON Schema:https://json.schemastore.org/claude-code-settings.json
• 权限文档:https://code.claude.com/docs/en/permissions.md
• Hooks 文档:https://code.claude.com/docs/en/hooks.md

.claude/commands/<name>.md — Slash Command #

【Claude Code 硬约定】

• 目录 .claude/commands/ 固定。
• 文件名 = slash command 名。goldeneyes-harness.md → /goldeneyes-harness。
• 子目录会变成 namespace(commands/git/commit.md → /git:commit)。

格式(frontmatter) #

【Claude Code 硬约定】

---
description: Route a formal requirement through the GoldenEyes harness  # 必填
argument-hint: "<需求描述>"                                              # 可选,显示在自动补全里
allowed-tools: Bash(git diff:*) Read                                     # 可选,这条命令可用工具白名单
model: claude-opus-4-7                                                   # 可选,模型覆盖
disable-model-invocation: true                                           # 可选,禁止 Claude 自动触发(只能用户输入)
---

正文 markdown。可以用以下占位符:
- $ARGUMENTS         所有参数
- $1, $2, ...        第 N 个参数
- @path/to/file      引用文件,Claude 会自动读
- !`command`         在传给 Claude 前先执行 bash 并把输出注入正文

GoldenEyes 当前的 goldeneyes-harness.md #

---
description: Route a formal requirement through the GoldenEyes harness
argument-hint: "<需求描述>"
---

Use the `goldeneyes-harness-request` skill to handle this requirement under the GoldenEyes harness.

请求内容:

$ARGUMENTS

执行步骤要求:
1. 先读 `.harness/current-task.json` 与 `.harness/tasks/index.json`...
2. 按 `references/task-file-contract.md` 创建或切换任务目录。
...

与 Skill 的关系 #

官方现在推荐用 skill 取代 commands,但旧的 commands/<name>.md 仍然有效。GoldenEyes 同时使用两种:slash command 是手动入口,skill 是自动入口(Claude 看 description 自动选)。

.claude/skills/<name>/SKILL.md — 项目级 Skill #

【Claude Code 硬约定】

• 目录 .claude/skills/ 固定。
• 每个 skill 是一个目录,里头必须有 SKILL.md(全大写,文件名固定)。
• 目录名建议与 frontmatter 的 name 一致;Claude 会从 SKILL.md 的 name 字段决定 skill 名。

作用域:

• .claude/skills/<name>/ — 项目级
• ~/.claude/skills/<name>/ — 用户级
• 插件提供的 skill — 由插件目录决定

SKILL.md 的 frontmatter #

【Claude Code 硬约定】

---
name: goldeneyes-harness-request           # 必填,与目录名匹配
description: Route formal requirements...  # 必填,Claude 据此决定何时自动选用此 skill
disable-model-invocation: false            # 可选,默认 false。true = 只能用户用 /name 调用
user-invocable: true                       # 可选,默认 true。false = 在 /菜单中隐藏,只能 Claude 自动触发
allowed-tools: Bash Read                   # 可选,本 skill 调用范围内的工具白名单
model: claude-opus-4-7                     # 可选,模型覆盖
effort: xhigh                              # 可选,推理强度
context: fork                              # 可选,fork = 在隔离子 agent 中跑
agent: Explore                             # 可选,context: fork 时用哪种子 agent
argument-hint: [issue-number]              # 可选,自动补全提示
arguments: [issue, branch]                 # 可选,命名位置参数映射
paths: "src/**/*.ts"                       # 可选,只在编辑这些文件时加载
shell: bash                                # 可选,bash(默认) | powershell
---

正文是给 Claude 看的"工作手册"。

几个关键字段的影响 #

• description:最关键。Claude 看这一行决定要不要自动选用此 skill。要写得具体,包含触发关键词。
• disable-model-invocation:控制 Claude 能不能自己挑这个 skill。true 时只有用户 /<name> 才能调用。
• user-invocable:控制用户能不能在 / 菜单里看到。
• allowed-tools:写在 frontmatter 里的工具,在该 skill 运行期间无需额外授权。
• context: fork:把 skill 放进隔离子 agent(参考 .claude/agents/),不污染主会话上下文。

GoldenEyes 当前的 SKILL.md #

---
name: goldeneyes-harness-request
description: Route formal requirements for GoldenEyes through its harness. Use when Claude Code should create or resume task context, run planner/coder/code_reviewer/verifier/doc_gardener, apply uncertainty gates, runtime or visual verification, git lifecycle, and docs sync.
---

只用了两个必填字段,其他全部走默认值。description 列了一长串触发词(planner/coder/code_reviewer/verifier/doc_gardener、uncertainty gates、runtime verification、visual verification、git lifecycle…)用来"钓"Claude 自动选用。

正文结构(本项目自定) #

SKILL.md 正文无固定 schema。GoldenEyes 这份用了 5 个段:

• Read First — 22 个文件的强制读取清单。
• Conditional References — 触发关键词路由(截图/Figma → visual-task-profile.md…)。
• Core Rule — 22 条核心规则。
• Claude Code 工具映射 — AskUserQuestion / EnterPlanMode / 子 agent 各自的适用场景。
• Start Or Resume / Stages / Finish — planner / coder / code_reviewer / verifier / doc_gardener 五阶段责任。

触发逻辑(官方) #

1. Claude 启动会话时,扫描所有 skill 的 frontmatter description(只看 description,不读正文)。
2. 当用户消息包含与 description 匹配的关键词,Claude 完整加载 SKILL.md + 相关 references/* 进上下文。
3. disable-model-invocation: true 时不会自动加载,必须用户 /<name>。

辅助子目录(本项目自定) #

4 个子目录的来源:references/ / scripts/ / assets/ 是 Anthropic 在 “Agent Skills” 文档中给出的推荐结构(progressive disclosure 模式),Claude Code 沿用了这套约定。examples/ 是社区常见做法,但不是官方明文约定。agents/ 完全是 GoldenEyes 自定义,Claude Code 不读。

references/ — 知识库(progressive disclosure 主战场) #

它解决什么问题:SKILL.md 不能塞太多内容(每次 description 命中都全量注入,贵)。把"细节、checklist、协议、字段契约"拆到 references,只在需要时由 Claude 主动 Read。

触发机制:

• Claude 不会自动加载 references/*,即便 description 命中。
• 加载方式只有一种:SKILL.md 正文(或上层 CLAUDE.md / task-package.yaml)显式提名让 Claude Read 它。
• 因此每篇 reference 都应该被至少一处显式引用,否则就是死文件。

文件命名:

• kebab-case,主题导向,一篇一主题:task-routing.md、code-review.md、git-workflow.md。
• 避免 notes.md、misc.md、extra.md 这种泛指名。
• 文件名要能让 Claude 仅凭名字判断"是否需要读"(因为正文不会自动注入)。

骨架模板(直接复制):

# <Protocol/Checklist 名称>

> 一句话:本文件给谁(planner / coder / verifier...)、什么时候(stage X 切换前 / 改某类文件时)、做什么用。

## 核心规则
- 用祈使句 + 完整断言。
- 避免"可能""一般""通常",写就写死。
- 每条规则前后不留隐含上下文。

## 触发条件
何时必须读这份文档:
- 关键词 A 出现在需求里
- 文件 X 被改动
- 状态从 P 切到 Q 之前

## 执行步骤
1. 先做 X。
2. 不能跳过 Y。
3. 完成后必须写入 `<task-dir>/<file>.md` 的 `<段落>` 字段。

## 输出契约
本协议执行后应产生:
- `decision-log.md` 追加一条 `{date, choice, reason}`
- `state.json.status` 切到 `<state>`
- `events.ndjson` 追加 `{event: "...", ...}`

## 反例 / 边界
- 看起来像但其实不是的情况:...
- 与 `<other-reference>.md` 的边界:...

写法清单(借鉴 task-routing.md / uncertainty-gates.md 的成熟形式):

和 SKILL.md 的分工:

• SKILL.md 写"什么阶段做什么、读哪份 reference”。
• references/<topic>.md 写"这个动作怎么做、判定标准是什么”。
• 触发关键词放 SKILL.md,展开细节放 references。

examples/ — 范例 #

它解决什么问题:有些任务靠规则描述不直观,直接给"输入 → 输出"对照,Claude 会模仿得更准。

触发机制:与 references 相同,必须显式 Read。常见做法:在 reference 末尾写"参考 ../examples/<scenario>/ 的样例"。

目录结构推荐:

examples/
├── README.md                          # 必备,索引每个 scenario 演示什么
├── route-new-task/                    # 一个完整 scenario
│   ├── input.md                       # 触发输入(用户的原话)
│   ├── expected-output/
│   │   ├── task-package.yaml          # Claude 应产出的文件 1
│   │   ├── state.json                 # 应产出的文件 2
│   │   └── current-task.json.diff     # 应该如何更新已有文件
│   └── notes.md                       # 这个 scenario 教什么、易错点
├── resume-with-feedback/
│   └── ...
└── ambiguous-multi-match/
    └── ...

examples/README.md 模板:

# Examples Index

| Scenario | 目的 | 触发场景 | 关键文件 |
|---|---|---|---|
| `route-new-task` | 演示新需求 → 创建任务 | 用户说"新增 X 功能" | `expected-output/task-package.yaml` |
| `resume-with-feedback` | 演示续跑 + 反馈追加 | 用户说"继续上一个任务" | `expected-output/handoff.md.diff` |
| `ambiguous-multi-match` | 演示路由候选 2-3 个时的提问 | 多个旧任务相似 | `input.md` 末尾的 AskUserQuestion 示范 |

单个 scenario 的 input.md / notes.md 模板:

<!-- input.md -->
## 场景
用户在 plan mode 之外直接说:

> "上次那个 AI 面板的还原度还不够,继续改一下右侧 timeline 的间距。"

## 当前 .harness 状态
- `current-task.json.task_key`: `2026-04-27/feature/video-panel-redesign`
- `index.json` 中该任务 `status`: `ready_for_human_review`

<!-- notes.md -->
## 这个 scenario 教什么
- 续跑判定:用户用"继续/上次/还不够"应触发续跑而非新建。
- 不要因为状态是 `ready_for_human_review` 就拒绝接收新反馈。

## 易错点
- 误判为新任务:导致 task_key 重复、index.json 出现兄弟任务。
- 跳过 `events.ndjson` 的 `feedback_received` 事件。

写法清单:

• 一个 scenario 一个目录,不要把多个例子塞同一个文件。
• 输入和期望输出分开存,这样 Claude 一眼能区分"读什么 / 产什么"。
• 期望输出尽量给完整文件内容,而不是 diff 片段(Claude 处理整文件比 patch 更稳)。
• 在 README.md 顶部用表格列清单,方便 Claude 决定读哪个。

scripts/ — 可执行脚本 #

它解决什么问题:有些操作(模板渲染、批量校验、生成 schema、自动同步)写成 deterministic 脚本比让 Claude 每次手写更可靠、更省 token。

触发机制:Claude 通过 Bash 工具显式调用,不会自动跑。SKILL.md 或 reference 里要写明"在 X 阶段调用 scripts/<name>.{sh,py}"。

目录结构推荐:

scripts/
├── README.md              # 索引:每个脚本干什么、输入/输出、退出码含义
├── create-task-dir.sh     # 按 task_key 生成任务目录骨架
├── validate-state.py      # 校验 state.json / events.ndjson 结构
└── sync-index.sh          # 把任务变更回写到 .harness/tasks/index.json

脚本骨架模板(以 bash 为例):

#!/usr/bin/env bash
# 名称: create-task-dir.sh
# 用途: 按 task_key 在 .harness/tasks/ 下生成任务目录骨架
# 输入:
#   $1 - task_key,形如 YYYY-MM-DD/type/short-slug
#   stdin (可选) - JSON {title, goal, context}
# 输出:
#   stdout - 创建的目录路径
#   退出码 0=成功 / 2=参数错 / 3=目录已存在
# 调用位置: 由 SKILL.md "Start Or Resume" 阶段在 planner 进入前调用
set -euo pipefail

TASK_KEY="${1:?missing task_key}"
ROOT="${CLAUDE_PROJECT_DIR:-.}/.harness/tasks/${TASK_KEY}"
[[ -d "$ROOT" ]] && { echo "exists: $ROOT" >&2; exit 3; }

mkdir -p "$ROOT/input" "$ROOT/snapshots"
# ...
echo "$ROOT"

Claude Code 提供的环境变量(脚本里可直接用):

scripts/README.md 模板:

# Scripts Index

| 脚本 | 用途 | 何时调用 | 输入 | 输出 / 副作用 |
|---|---|---|---|---|
| `create-task-dir.sh <task_key>` | 生成任务目录骨架 | planner 进入前 | task_key | 创建 `.harness/tasks/<key>/...` |
| `validate-state.py <task-dir>` | 校验 state/events 结构 | 每次状态变化后 | task 目录路径 | 退出码 0/非 0 |
| `sync-index.sh` | 把任务最新状态回写到 index.json | task 状态变化时 | 无 | 修改 `.harness/tasks/index.json` |

## 跨平台注意
- Windows + Git Bash: 使用 `/c/...` 风格路径,避免反斜杠
- 所有脚本必须 `set -euo pipefail`,失败立即退出
- 不允许脚本输出非 ASCII 控制字符干扰 Claude 解析

写法清单:

• 每个脚本职责单一(一个动词)。
• 退出码语义化(0 成功 / 2 用法错 / 3 状态冲突),Claude 据此判断要不要重试或提问。
• 输入/输出走 stdin/stdout/退出码,不要往 stderr 写正常输出。
• Windows 用户多时,优先 bash 脚本(MSYS / Git Bash)而非 PowerShell,跨平台一致。
• 大型脚本拆 Python(有依赖管理) + 小工具用 shell。

agents/ — 本项目自定的展示元信息 #

官方约定? 不是。Claude Code 没有"在 skill 内部嵌套 agent 定义"的机制,真正的 subagent 在 ./.claude/agents/<name>.md(参见第 9.1 节)。

GoldenEyes 为什么这么用:把"给不同 Agent CLI(Claude / Codex)看的 UI 文案"打包到 skill 目录内,方便两端镜像同步。当前用法纯展示,Claude Code 不会读取。

现状:

.claude/skills/goldeneyes-harness-request/agents/
└── claude.yaml

.agents/skills/goldeneyes-harness-request/agents/
└── openai.yaml

两份 yaml 字段一致,只是 default_prompt 微调以适配不同 Agent CLI 的提示语气。

agents/<vendor>.yaml 模板:

interface:
  display_name: "<面向人类的标题>"
  short_description: "<一句话,~50 字,展示在工具菜单>"
  default_prompt: "<用户没输入时的默认 prompt 文本>"
  # 可选:
  category: "harness | review | docs | ..."
  keywords: ["harness", "task-routing", ...]
  icon: "🛠"                # 仅用于自家文档前端
  hidden: false

会被谁消费?

• Claude Code / Codex CLI 都不会自动读它(目前)。
• 仅供:harness-project-bootstrap/ 等自家工具生成展示页;或团队内部前端从仓库扫 yaml 渲染 skill 库。

写法清单:

• 字段保持两端一致;default_prompt 可针对 vendor 微调,但语义不能改。
• 不要往这里塞工作流规则——那是 references 的活。
• 如果有一天要换成真正的 subagent,改去 .claude/agents/<name>.md(官方支持),不要在这个 yaml 里塞 system_prompt 之类的字段假装是 subagent。

三种"加载粒度"对比 #

经验法则:写规则前先想"这条规则是每次命中都要,还是只在某阶段才用"。前者放 SKILL.md,后者放 references。能写成脚本的,优先脚本。

.harness/ — 工程级事实数据 #

名称 #

【本项目自定】 .harness/ 不是任何 Agent CLI 的硬约定,完全是 GoldenEyes 自家的设计。CLAUDE.md / SKILL.md 把它当成必读上下文,所以才被 Claude 反复加载。

文件分类 #

.harness/current-task.json(关键索引) #

{
  "schema_version": "1.0",
  "task_key": "2026-04-27/feature/video-panel-redesign",
  "title": "复刻视频取证工具页面",
  "status": "ready_for_human_review",
  "branch": "harness/feature/video-panel-redesign",
  "updated_at": "2026-04-27T20:30:00+08:00",
  "summary": "等待用户确认视觉还原程度"
}

服务"继续上一个任务"语义。无活跃任务时各字段为 null。

.harness/tasks/index.json(任务总账) #

{
  "schema_version": "1.0",
  "updated_at": "2026-04-27T20:30:00+08:00",
  "tasks": [
    {
      "task_key": "2026-04-27/feature/video-panel-redesign",
      "title": "复刻视频取证工具页面",
      "type": "feature",
      "slug": "video-panel-redesign",
      "status": "ready_for_human_review",
      "branch": "harness/feature/video-panel-redesign",
      "created_at": "2026-04-27T20:00:00+08:00",
      "updated_at": "2026-04-27T20:30:00+08:00",
      "keywords": ["视频取证", "页面复刻", "AI识别"],
      "task_path": ".harness/tasks/2026-04-27/feature/video-panel-redesign"
    }
  ]
}

.harness/tasks/<YYYY-MM-DD>/<type>/<short-slug>/(任务工作目录) #

每个正式任务的"工作目录"。骨架(详见 task-file-contract.md):

input/requirement.md             # 用户原始需求
task-package.yaml                # 任务总信息(下面有详细字段)
problem-decomposition.md         # 问题拆解
research-notes.md                # (条件)调研笔记
functional-test-plan.md          # (条件)功能点测试计划
runtime-test-plan.md             # (条件)运行时测试计划
interaction-test-plan.yaml       # (条件)交互测试计划
acceptance-criteria.md           # 验收标准(机器/行为/人工三段)
exec-plan.md                     # 执行计划
decision-log.md                  # 决策记录
handoff.md                       # 阶段交接
code-review-report.md            # 代码评审报告
verification-report.md           # 验证报告
doc-sync-report.md               # 文档同步报告
trace.md                         # 追踪
summary.md                       # 短摘要(给前端读)
state.json                       # 机器可读状态(主入口)
events.ndjson                    # 追加式事件流
agents.json                      # 5 个角色公开状态
artifacts.json                   # 任务产物清单
validations.json                 # 机器验证/运行时检查/交互检查/人工验收

视觉任务再加 visual-spec.md、visual-checklist.md、visual-review.md、visual-defects.md、snapshots/。

task-package.yaml 关键字段 #

task_key: "2026-04-24/feature/short-title"        # 任务唯一键 = 目录路径
parent_task: null                                  # 父任务 task_key
related_tasks: []                                  # 相关任务列表
route_reason: "new_request"                        # 路由原因
branch: "harness/feature/short-title"              # 任务分支名
created_at: "2026-04-24"
title: "一句话标题"
status: "planned"                                  # 见下方状态机
goal: "本任务要达成的用户可见结果"
context: "需求背景..."
constraints: ["遵守 AGENTS.md 与 ARCHITECTURE.md"]
done_when: ["..."]                                 # 验收完成条件
read_first: ["AGENTS.md", "ARCHITECTURE.md", ...]  # 任务级必读清单
verification_commands: ["go vet ./...", ...]
git_strategy:
  branch: "harness/feature/short-title"
  create_or_switch_before_coding: true
  affiliated_subrepo_branch_policy: "无 .harness 的附属子仓库使用同名任务分支"
  commit_policy: "模块闭环、风险边界或约 300-500 行变更量时提交"
  push_policy: "不自动 push"
related_project_edit_scope:
  - path: "../shared-lib"
    harness_status: "absent"          # absent | present | unknown
    write_policy: "allowed_by_default"
    branch: "harness/feature/short-title"
assumptions: []

任务状态机(本项目自定) #

state.json.status 取值序列(节选):

planned
  → needs_clarification | blocked_on_decision      # 不确定性闸门
  → coding
  → needs_code_review
    → code_review_failed → coding                  # 评审打回
  → needs_verification
    → verification_failed → coding                 # 验证失败
  → needs_visual_verification                      # 视觉任务专用
  → ready_for_human_review
  → accepted | cancelled

本项目未使用但官方支持 #

一次会话如何串起来 #

[Claude Code 启动]
  └── 自动加载 ./CLAUDE.md(注入会话顶部)
  └── 自动扫描 .claude/skills/*/SKILL.md frontmatter

[用户输入需求]
  ├── 如果用 /goldeneyes-harness <文本>
  │     → 走 .claude/commands/goldeneyes-harness.md
  └── 如果用自然语言
        → Claude 看 SKILL.md description 命中
        → 自动加载 .claude/skills/goldeneyes-harness-request/SKILL.md

[skill 内部流程,按 SKILL.md "Start Or Resume" 段]
  1. 读 .harness/current-task.json 与 tasks/index.json,按 references/task-routing.md 路由
  2. 必读 22 个文件:ARCHITECTURE.md + .harness/* + 任务目录文件
  3. planner: 写 task-package.yaml / problem-decomposition.md / acceptance-criteria.md / 等
  4. coder: 切到 harness/<type>/<short-slug> 分支后实现
  5. code_reviewer: 写 code-review-report.md;blocking 项不通过则回 coder
  6. verifier: 跑 go test/vet 等必跑传感器,前端任务用 MCP Playwright
  7. 同步 state.json / events.ndjson / agents.json / artifacts.json / validations.json / summary.md
  8. 最终交付总结(做了什么 / 为什么 / 验证 / 残余风险 / 下个会话先读什么)

[全程触发的横切机制]
  - settings.local.json 控制 Bash/Read 是否要弹窗
  - AskUserQuestion 收集结构化决策(写入 decision-log.md)
  - TaskCreate/TaskUpdate 跟踪本会话步骤(与 .harness/tasks 是两层概念)
  - EnterPlanMode 在大改前与用户对齐 plan