Harness Setup

Harness Setup

Harness の統合セットアップスキル。 以下の旧スキルを統合:

• setup — 統合セットアップハブ
• harness-init — プロジェクト初期化
• harness-update — Harness アップデート
• maintenance — ファイル整理・クリーンアップ

Quick Reference

Built-in slash discovery (CC 2.1.108+): /init のような built-in slash command も発見される。 Harness 固有の bootstrap が必要な時だけ /harness-setup init と使い分ける。

Claude Code setup guidance (CC 2.1.120+): MCP alwaysLoad、${CLAUDE_EFFORT}、claude plugin prune、claude project purge、 ANTHROPIC_BEDROCK_SERVICE_TIER、claude_code.skill_activated.invocation_trigger、 Windows PowerShell primary shell、forked skills / subagents の deferred tools は docs/claude-code-setup-mcp-telemetry-provider.md を正本として扱う。

Codex plugin workflows: Codex /goal と Plans.md を二重管理しない。 plugin-bundled hooks は opt-in、external agent import は ownership 明記、 MultiAgentV2 / agents.max_threads = 8 は上限として扱い、 sticky environments / app-server artifacts は safe default を優先する。 Codex 0.130.0 stable の codex remote-control、large thread pagination、 selected-environment view_image、live app-server config refresh、 accurate turn diffs、plugin details bundled hooks、sharing discoverability controls は docs/codex-plugin-workflows-policy.md を正本として扱う。 詳細は docs/codex-plugin-workflows-policy.md を参照。

サブコマンド詳細

init — プロジェクト初期化

新規プロジェクトに Harness を導入する。

生成ファイル:

project/
├── CLAUDE.md            # プロジェクト設定
├── Plans.md             # タスク管理（空テンプレート）
├── .claude/
│   ├── settings.json    # Claude Code 設定
│   └── hooks.json       # フック設定（Go バイナリ）
└── hooks/
    ├── pre-tool.sh      # 薄いシム（→ core/src/index.ts）
    └── post-tool.sh     # 薄いシム（→ core/src/index.ts）

フロー:

1. プロジェクト種別を検出（Node.js/Python/Go/Rust/その他）
2. 最小限の CLAUDE.md を生成
3. Plans.md テンプレートを生成
4. hooks.json を配置
5. Go バイナリ検証: harness version でバイナリが利用可能か確認（v4.0 以降 Node.js 不要）
6. プラグインファイル同期: harness sync で .claude-plugin/ 配下のファイルを最新に同期。harness.toml が無く sync が失敗する場合は先に harness init を実行する（Setup hook 導入前にブートストラップされたプロジェクトの復旧経路）
7. ヘルスチェック: harness doctor で全チェック項目をパス。問題があれば修正案を提示

Go バイナリ検証

# バイナリの存在と動作を確認
harness version
# 例: harness v4.0.0 (go1.22.0, darwin/arm64)

v4.0 以降、Harness のコアエンジンは Go バイナリに移行した。 Node.js は不要。バイナリは bin/harness（または PATH 上の harness）を使用する。

プラグインファイル同期

# .claude-plugin/ 配下のファイルを最新に同期
harness sync

# 同期内容の確認のみ（変更なし）
harness sync --dry-run

harness sync は skills/ の SSOT から各 mirror（codex/.codex/skills/、opencode/skills/）へ 変更を伝播させる。init 後に必ず実行すること。

ヘルスチェック

# 全チェック項目を実行
harness doctor

harness doctor は以下を確認する:

問題が検出された場合は修正コマンドを提示する。

ci — CI/CD 設定

GitHub Actions ワークフローを設定する。

# .github/workflows/ci.yml 生成例
name: CI
on:
  push:
    branches: [main]
  pull_request:
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

codex — Codex CLI 設定

# インストール確認（Codex CLI は Node.js ベース。Harness 本体とは別物）
which codex || npm install -g @openai/codex

# タイムアウトコマンド確認（macOS）
TIMEOUT=$(command -v timeout || command -v gtimeout || echo "")
# macOS の場合: brew install coreutils

注意: Harness v4.0 本体（harness コマンド）は Node.js 不要の Go バイナリ。 Codex CLI（codex コマンド）は別ツールであり、引き続き Node.js が必要。

Codex provider / model metadata policy (0.123.0+ / 0.130.0)

Codex 0.123.0 以降の provider / model guidance と、Codex 0.130.0 stable の Bedrock aws login guidance は docs/codex-provider-setup-policy.md を正本として扱う。

要点:

• Bedrock を使う場合は、Codex built-in provider の amazon-bedrock を使う。
• AWS profile は user / project の Codex config で [model_providers.amazon-bedrock.aws] に置く。
• AWS console-login credentials from aws login profiles は AWS 側の profile material として扱う。
• Harness は AWS credential、console-login cache、provider endpoint を書き込まない。
• Harness の配布用 Codex config には model = "gpt-5.4" を setup default として固定しない。
• Harness の配布用 Codex config には model_provider = "amazon-bedrock" も setup default として固定しない。
• gpt-5.4 は Codex 本体の current model metadata として扱い、古い gpt-5.2-codex などを推奨 sample として残さない。
• Claude Code 側の CLAUDE_CODE_USE_BEDROCK / ANTHROPIC_DEFAULT_* / modelOverrides guidance と、Codex の model_provider = "amazon-bedrock" は混ぜない。

Bedrock を使う user / project だけが、必要に応じて次を追加する:

model_provider = "amazon-bedrock"

[model_providers.amazon-bedrock.aws]
profile = "codex-bedrock"

Claude Code 側の provider / MCP / telemetry guidance は docs/claude-code-setup-mcp-telemetry-provider.md を参照する。 特に ANTHROPIC_BEDROCK_SERVICE_TIER は Bedrock 利用者の provider 環境だけで扱い、 Harness の plugin default / template / shared project settings には入れない。

Codex app-server / plugin workflow policy (0.130.0)

Codex 0.130.0 stable (rust-v0.130.0, published 2026-05-08T23:09:55Z) の app-server / plugin workflow guidance は docs/codex-plugin-workflows-policy.md を正本として扱う。

要点:

• codex remote-control は headless remotely controllable app-server の明示起動 entrypoint。Harness setup は remote-control defaults を config に書かない。
• App-server clients can page large threads。長い loop / Breezing transcript は必要な page 範囲を確認する。
• view_image は multi-environment session の selected environments 経由で file を解決できる。artifact report には environment / workdir を添える。
• Live app-server threads pick up config changes without restart。ただし secret / provider / hook policy の変更は diff と verification で扱う。
• Turn diffs stay accurate across apply_patch including partial failures。最終判断は git diff と tests で確認する。
• Plugin details now show bundled hooks。install / share 前に bundled hooks を確認し、Harness bundled hooks は opt-in のままにする。
• Plugin sharing exposes link metadata and discoverability controls。公開範囲と metadata は release surface として確認する。
• Configurable OpenTelemetry trace metadata は debugging / triage 補助に限定し、個人情報・顧客情報・secret を入れない。
• Built-in MCPs first-class runtime servers は Codex runtime owned surface として扱い、plugin-provided MCP と所有者を混ぜない。
• CODEX_HOME environments TOML provider は user-level environment source。選択 environment を報告し、write turn は one primary environment に固定する。
• Remove skills list extra roots に依存せず、Harness mirror install または [[skills.config]] path-based loading を明示する。

Codex MCP diagnostics / plugin loading (0.123.0+)

Codex 0.123.0 以降の MCP diagnostics / plugin MCP loading guidance は docs/codex-mcp-diagnostics.md を正本として扱う。

要点:

• Codex TUI では、普段は /mcp で軽量に server 状態だけ確認する。
• MCP server が見えない、resources が出ない、resource templates が読めない時だけ /mcp verbose を使う。
• /mcp verbose では diagnostics / resources / resource templates を確認する。
• plugin 内 .mcp.json は mcpServers 形式と top-level server map 形式の両方を受け取れる前提で案内する。
• 新規 plugin では共有しやすい mcpServers 形式を優先する。
• 既存 plugin が top-level server map 形式なら、Codex 側の loading 改善を利用し、不要な書き換えを避ける。
• Claude Code 側の claude mcp ...、.claude/mcp.json、hook type: "mcp_tool" guidance と混ぜない。

mcpServers 形式:

{
  "mcpServers": {
    "docs": {
      "command": "node",
      "args": ["server.js"]
    }
  }
}

top-level server map 形式:

{
  "docs": {
    "command": "node",
    "args": ["server.js"]
  }
}

Codex sandbox / execution policy (0.123.0+)

Codex 0.123.0 以降の remote_sandbox_config と codex exec shared flags guidance は docs/codex-sandbox-execution-policy.md を正本として扱う。

要点:

• remote_sandbox_config は requirements.toml の host-specific sandbox policy として案内する。
• remote devbox / ephemeral CI runner / shared host のように、remote environment ごとの allowed_sandbox_modes を比較して決める。
• host matching は便利な分類だが、強い device authentication ではない。高リスク環境では broad wildcard を避ける。
• Harness の配布用 codex/.codex/config.toml には organization-specific な remote_sandbox_config を書かない。
• Codex 0.123.0 以降は codex exec が root-level shared flags を継承するため、wrapper 側で重複した --approval-policy / --sandbox pairs を追加しない。
• scripts/codex-companion.sh task --write が --sandbox workspace-write を付けるのは、Harness の「書き込みタスク」という意図を exec-local に変換しているためであり、root shared flags の重複転送ではない。
• scripts/codex/codex-exec-wrapper.sh の --full-auto は 53.2.4 では維持する。変更する場合は別 task で approval / sandbox behavior の回帰テストを追加する。

requirements example:

allowed_sandbox_modes = ["read-only"]

[[remote_sandbox_config]]
hostname_patterns = ["devbox-*.corp.example.com"]
allowed_sandbox_modes = ["read-only", "workspace-write"]

使用パターン（公式プラグイン経由）:

bash scripts/codex-companion.sh task --write "タスク内容"
# または stdin 経由
cat /tmp/prompt.md | bash scripts/codex-companion.sh task --write

Cursor 実装バックエンド導入（脳 Opus / 体 composer）

Cursor を Harness の実装（worker）バックエンドとして使うための導入手順。 レビュー / advisor ロールは Opus に固定し、cursor バックエンドへ切り替えない（.claude/rules/cursor-cli-only.md の Role scope）。

1. AI 実行可（バックエンド選択の永続化）

set-impl-backend.sh でバックエンドを永続化する。Harness / AI がこのステップを実行できる。

# プロジェクトスコープ（このプロジェクトの env.local に書く）
bash "${HARNESS_PLUGIN_ROOT}/scripts/set-impl-backend.sh" cursor

# ユーザースコープ（全プロジェクト共通: ${HOME}/.config/claude-harness/impl-backend.env）
bash "${HARNESS_PLUGIN_ROOT}/scripts/set-impl-backend.sh" --user cursor

# 現在解決されるバックエンドを表示して確認
bash "${HARNESS_PLUGIN_ROOT}/scripts/set-impl-backend.sh" --show

解決の優先順位: プロジェクト env.local がユーザースコープより優先される。

2. ユーザー手動（AI は編集不可。protected path + sandbox のため）

以下 3 ファイルは Edit/Write(.claude/settings*) deny と self-audit guard、および ~/.cursor/* が plugin write 対象外であるため Harness / AI が編集できない。ユーザー自身がターミナル / エディタで設定する。

• ~/.cursor/permissions.json: terminalAllowlist / mcpAllowlist を追加する。 テンプレートは .claude/rules/cursor-cli-only.md の ~/.cursor/permissions.json テンプレートを使う。 --force / Run Everything（--yolo）は使わない（Cursor 公式が "Never use"）。
• .cursorignore: secrets（.env, *.pem, *.key, .ssh, .aws, .git）を列挙する。 テンプレートは .claude/rules/cursor-cli-only.md の .cursorignore テンプレートを使う。
• ~/.claude/settings.json の sandbox（2 点）: (1) network.allowedDomains に *.cursor.sh を追加、 (2) 公式キー sandbox.filesystem.allowWrite に ~/.cursor を追加する（cursor-agent は実行時に ~/.cursor/projects/... と ~/.cursor/cli-config.json.tmp へ状態を書くため、未許可だと EPERM で失敗する）。⚠️ キー名は allowWrite: write という名前にすると未知キーとして 無視され設定が効かない（実測で確認）。~/ は sandbox 側で展開される（公式例 ["~/.kube"]）。 両方揃うと per-run の sandbox 無効化なしで実行できる。手順は docs/sandbox-allowlist-recipe.md の jq merge レシピと .claude/rules/cursor-cli-only.md の「Sandbox 要件」に従う。CC 完全再起動後に有効化される。

3. 境界（cursor は candidate のまま）

cursor バックエンドは candidate の位置づけ。安全性は Cursor の allowlist（best-effort、bypass 可能）ではなく、 専用 .git を持つ worktree での隔離実行 + Lead による diff レビュー + cherry-pick での本流取り込みで担保する。 cursor-agent の出力は Lead レビューまで untrusted として扱う。詳細は .claude/rules/cursor-cli-only.md を参照。

harness-mem — メモリ設定

Unified Harness Memory の設定を行う。

# メモリディレクトリ作成
mkdir -p .claude/agent-memory/claude-code-harness-worker
mkdir -p .claude/agent-memory/claude-code-harness-reviewer

# MEMORY.md テンプレート配置
cat > .claude/agent-memory/claude-code-harness-worker/MEMORY.md << 'EOF'
# Worker Agent Memory

## Project Context
[プロジェクト概要]

## Patterns
[学習パターン]
EOF

mirrors — 公開 skill bundle 同期

Windows の core.symlinks=false では repository symlink が通常ファイルになり、harness-* skill が command 一覧に出なくなることがあります。公開 bundle は実ディレクトリ mirror として同期します。

./scripts/sync-skill-mirrors.sh
./scripts/sync-skill-mirrors.sh --check

更新対象:

• skills/
• codex/.codex/skills/
• opencode/skills/

agents — エージェント設定

agents/ の3エージェント構成を設定する。

agents/
├── worker.md      # 実装担当（task-worker + codex-implementer + error-recovery）
└── reviewer.md    # レビュー担当（code-reviewer + plan-critic）

localize — ルールローカライズ

.claude/rules/ のルールを現プロジェクトに適応する。

# ルール一覧確認
ls .claude/rules/

# プロジェクト固有ルールの追加
cat >> .claude/rules/project-rules.md << 'EOF'
# Project-Specific Rules
[プロジェクト固有ルール]
EOF

Plugin インストール (v2.1.71+ Marketplace)

v2.1.71 で Marketplace の安定性が大幅に改善された。 Claude Code 2.1.117-2.1.118 以降の plugin / managed settings 方針は docs/plugin-managed-settings-policy.md を正本として扱う。

推奨インストール方式

# @ref 形式でバージョン固定（推奨）
claude plugin install owner/repo@v4.0.0

# 最新版
claude plugin install owner/repo

owner/repo@vX.X.X 形式を推奨。@ref パーサー修正により、タグ・ブランチ・コミットハッシュいずれも正確に解決される。

アップデート

claude plugin update owner/repo

v2.1.71 で update 時の merge conflict が修正され、安定したアップデートが可能になった。

その他の改善点

• MCP server 重複排除: 同一 MCP サーバーの多重登録を自動防止
• /plugin uninstall が settings.local.json を使用: ユーザーローカル設定に正確に反映

Managed marketplace / dependency policy (v2.1.117+)

企業利用で plugin marketplace を制御する場合は、Claude Code 本体の managed settings を使う。 Harness は独自の marketplace resolver や dependency resolver を重ねない。

DISABLE_AUTOUPDATER は自動更新を止める。 DISABLE_UPDATES は手動 claude update まで止めるため、企業の固定バージョン運用向け。 Harness の project default にはどちらも入れず、必要な組織が managed settings または端末管理で設定する。

依存関係が欠けた場合は、まず Claude Code の /plugin Errors、/doctor、claude plugin list --json を確認する。 marketplace 未登録が原因なら /plugin marketplace add または claude plugin marketplace add で登録し、本体の auto-resolve に任せる。

Maintenance — ファイル整理

定期メンテナンスタスク:

関連スキル

• harness-plan — セットアップ後にプロジェクト計画を作成
• harness-work — セットアップ後にタスクを実行
• harness-review — セットアップ設定をレビュー