harness-setup

Harness Setup

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

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

Quick Reference

サブコマンド	動作
/harness-setup init	新規プロジェクト初期化（CLAUDE.md + Plans.md + hooks + sync + doctor）
/harness-setup ci	CI/CD パイプライン設定
/harness-setup codex	Codex CLI インストール・設定
/harness-setup harness-mem	harness-mem 統合・メモリ設定
/harness-setup mirrors	skills/ → 公開 mirror bundle 更新
/harness-setup agents	agents/ エージェント設定
/harness-setup localize	CLAUDE.md ルールのローカライズ

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

サブコマンド詳細

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/ 配下のファイルを最新に同期
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 は以下を確認する:

チェック項目	内容
バイナリ	harness version が正常に返るか
プラグイン設定	.claude-plugin/plugin.json の形式が正しいか
hooks 配置	hooks が正しいパスに存在するか
mirror 同期	skills/ と mirror の内容が一致しているか
CLAUDE.md	必須セクションが存在するか

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

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+)

Codex 0.123.0 以降の provider / model 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] に置く。
• Harness は AWS credential や provider endpoint を書き込まない。
• Harness の配布用 Codex config には model = "gpt-5.4" を 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"

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

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）
└── scaffolder.md  # 足場担当（project-analyzer + scaffolder）

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 を重ねない。

項目	用途	Harness の扱い
extraKnownMarketplaces	チームに推奨 marketplace を案内・登録する	通常の onboarding ではこちらを優先
blockedMarketplaces	特定 marketplace source をブロックする	managed settings 専用。通常ユーザー向け default には入れない
strictKnownMarketplaces	許可した marketplace source だけ追加できるようにする	managed settings 専用。通常ユーザー向け default には入れない
plugin dependency auto-resolve	dependencies の自動 install / missing dependency hints	Claude Code 本体に任せる。Harness 独自 resolver は追加しない
plugin themes/ directory	plugin が theme を配布する	今回は P: 将来タスク。Harness は theme を同梱しない

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 — ファイル整理

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

タスク	コマンド
古いログ削除	find .claude/logs -mtime +30 -delete
Plans.md 圧縮	完了タスクをアーカイブセクションに移動
古いトレース削除	tail -1000 .claude/state/agent-trace.jsonl > /tmp/trace && mv /tmp/trace .claude/state/agent-trace.jsonl

関連スキル

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