Skip to content

README_ja.md

Latest commit

 

History

History
494 lines (339 loc) · 18.5 KB

README_ja.md

File metadata and controls

494 lines (339 loc) · 18.5 KB
Raw

Claude Harness

Plan. Work. Review. Ship.
Claude Code を規律ある開発パートナーに変える

Latest Release License Claude Code Skills TypeScript Core

English | 日本語

なぜ Harness？

Claude Code は強力です。Harness はその力を、信頼しやすく、途中で崩れにくい開発フローへ変えます。

Harness を入れると変わること: 計画の定着、実行時ガード、やり直せる検証

5動詞スキルで流れを揃え、TypeScript ガードレールエンジンで実行を守り、検証は必要なときに同じ手順でやり直せます。

人気の Claude Code ハーネスと比べると

ここで見たいのは、Claude Code が理論上どこまでできるかではなく、ハーネスを入れたあとに 標準の進め方がどう変わるか です。

これは 2026-03-06 時点 の ユーザーに見える運用差 比較であり、人気投票ではありません。 根拠とソース一覧: docs/github-harness-plugin-benchmark.md

下のカードは、導入後に標準の進め方がどう変わるかだけを見せています。

Claude Harness、Superpowers、cc-sdd を導入した後の標準フロー比較

Claude Harness は、計画・実装・レビュー・検証を崩れにくい標準フローとして回したい人に向いています。

対応 baseline と最新の検証スナップショットは Claude Code 互換性 にまとめています。

動作要件

30秒でインストール

# プロジェクトで Claude Code を起動
claude

# マーケットプレイスを追加してインストール
/plugin marketplace add Chachamaru127/claude-code-harness
/plugin install claude-code-harness@claude-code-harness-marketplace

# プロジェクトを初期化
/harness-setup

これだけ。/harness-plan から始めよう。

🪄 説明が長い？ならこれ: 検証前提の /work all

読むのが面倒？ これだけ打てばいい:

/harness-work all

計画承認後の最短導線はこれです。 計画 → 並列実装 → レビュー → コミット。

/work all パイプライン

⚠️ 実験的ワークフロー: 計画を承認したら、Claude が完走します。実運用の前に docs/evidence/work-all.md で成功系/失敗系の契約を確認してください。

5動詞ワークフロー

Plan → Work → Review サイクル

0. Setup（初期化）

/harness-setup

以後の作業が同じルールとコマンド面で走るように、プロジェクトファイルと初期設定を揃えます。

1. Plan（計画）

/harness-plan

「メールバリデーション付きのログインフォームが欲しい」

Harness が明確な受入条件付きの Plans.md を作成。

2. Work（実装）

/harness-work              # 並列数を自動検出
/harness-work --parallel 5 # 5ワーカーで同時実行

各ワーカーが実装、セルフレビュー、報告を行う。

並列ワーカー

3. Review（レビュー）

/harness-review

4視点レビュー

視点 焦点
Security 脆弱性、インジェクション、認証
Performance ボトルネック、メモリ、スケーリング
Quality パターン、命名、保守性
Accessibility WCAG準拠、スクリーンリーダー

4. Release（リリース）

/harness-release

実装とレビューの結果を前提に、CHANGELOG、タグ、リリース用のハンドオフをまとめます。

セーフティファースト

安全保護システム

Harness v3 は TypeScript ガードレールエンジン（core/）でコードベースを保護 — 9つの宣言的ルール（R01–R09）、コンパイル済み＆型チェック済み:

ルール 保護対象 アクション
R01 sudo コマンド 拒否
R02 .git/, .env, シークレット 書き込み拒否
R03 rm -rf /, 破壊的パス 拒否
R04 git push --force 拒否
R05–R09 モード固有のガード コンテキスト判定
Post it.skip, アサーション改ざん 警告
Perm git status, npm test 自動許可

セーフティシールド

5動詞スキル、設定不要

v3 で42スキルを 5つの動詞スキルに統合。まずは動詞から入り、必要になったときだけ Breezing、Codex、2-Agent を足せます。

/plan

アイデア → Plans.md

/work

並列実装

/review

4視点コードレビュー

/release

タグ + GitHub Release

/setup

プロジェクト初期化

スキルエコシステム

主要コマンド

コマンド 機能 旧コマンド
/harness-plan アイデア → Plans.md /plan-with-agent, /planning
/harness-work 並列実装 /work, /breezing, /impl
/harness-work all 承認済み計画 → 実装 → レビュー → コミット /work all
/harness-review 4視点コードレビュー /harness-review, /verify
/harness-release CHANGELOG、タグ、GitHub Release /release-har, /handoff
/harness-setup プロジェクト初期化 /harness-init, /setup
/memory SSOT ファイルを管理 —

誰のためのツール？

あなたが Harness でできること
開発者 組み込み QA で高速に出荷
フリーランサー クライアントにレビューレポートを納品
インディーハッカー 壊さずに素早く動く
VibeCoder 自然言語でアプリを構築
チームリード プロジェクト横断で標準を強制

アーキテクチャ

claude-code-harness/
├── core/           # TypeScript ガードレールエンジン（strict ESM, NodeNext）
│   └── src/        #   guardrails/ state/ engine/
├── skills-v3/      # 5動詞スキル（plan/execute/review/release/setup）
├── agents-v3/      # 3エージェント（worker/reviewer/scaffolder）
├── hooks/          # 薄いシム → core/ エンジン
├── skills/         # 旧41スキル（互換性のため保持）
├── agents/         # 旧11エージェント（互換性のため保持）
├── scripts/        # v2 フックスクリプト（v3 core と共存）
└── templates/      # 生成テンプレート

高度な機能

Breezing（Agent Teams）

自律エージェントチームでタスクリストを一気に完走:

/harness-work breezing all                    # 計画レビュー + 並列実装
/harness-work breezing --no-discuss all       # 計画レビューをスキップして即実装
/harness-work breezing --codex all            # Codex エンジンに委託

Breezing エージェントチーム

Phase 0（計画議論） がデフォルトで実行されます。Planner がタスクの品質を分析し、Critic が計画を批判的にチェック。あなたが承認してからコーディングが始まります。

機能 説明
計画議論 Planner + Critic が計画をレビュー（デフォルトON）
タスク検証 (V1–V5) スコープ・曖昧さ・重複・依存・TDD をチェック
Progressive Batching 8タスク以上は自動でバッチ分割
Hook シグナル 部分レビューや次バッチの自動トリガー

コスト: デフォルトで約5.5倍のトークン（--no-discuss なら約4倍）。計画レビューにより手戻りが減るので投資対効果は高い。

Codex エンジン

実装タスクを OpenAI Codex に並列委託:

/harness-work --codex API エンドポイントを5つ実装して

Codex が実装 → セルフレビュー → 報告。Claude Code ワーカーと併用可能。

セットアップが必要: Codex CLI をインストールし、APIキーを設定。

Codex CLI セットアップ

Codex CLI で Harness を利用できます。Claude Code は不要です。

前提条件: Codex CLI（npm i -g @openai/codex）、OpenAI API キー（OPENAI_API_KEY）、Git。

# 1. Harness リポジトリをクローン
git clone https://github.com/Chachamaru127/claude-code-harness.git
cd claude-code-harness

# 2. スキル/ルールをユーザースコープ（~/.codex）にインストール
./scripts/setup-codex.sh --user

# 3. プロジェクトに移動して作業開始
cd /path/to/your-project
codex

Codex 内で $harness-plan、$harness-work、$breezing、$harness-review を使ってワークフローを実行します。

フラグ 説明
--user ~/.codex にインストール（プロジェクト横断で共有、デフォルト）
--project カレントディレクトリの .codex/ にインストール

Claude Code ユーザーはセッション内で /setup codex を実行するだけで同じセットアップが適用されます。

2-Agent モード（Cursor連携）

Cursor を PM として、Claude Code を実装者として使用。

/harness-release handoff  # Cursor PM に報告

Plans.md が両者間で同期。

Codex レビュー連携

OpenAI Codex でセカンドオピニオンを追加：

/harness-review --codex  # 4視点 + Codex CLI

Codex が codex exec 経由で、16種のスペシャリストから4人の関連エキスパートを選出。

スライド生成

1枚のプロジェクト紹介スライドを自動生成：

/generate-slide
  • 3つのビジュアルパターン（Minimalist / Infographic / Hero）
  • 各パターン2候補を品質スコアリング
  • 最良3枚を out/slides/selected/ に出力

前提: GOOGLE_AI_API_KEY と Google AI Studio の利用設定。

動画生成

JSON Schema 駆動のパイプラインでプロダクト動画を生成：

/generate-video
  • JSON Schema を SSOT (Single Source of Truth) として使用
  • 3層バリデーション: scene → scenario → E2E
  • Remotion ベースの決定論的レンダリング

依存関係: Remotion プロジェクトのセットアップと ffmpeg が必要。

Agent Trace

AI による編集操作を自動追跡：

.claude/state/agent-trace.jsonl
  • Edit/Write 操作をタイムスタンプ付きで記録
  • セッション終了時にプロジェクト名、現在のタスク、直近の編集を表示
  • /sync-status で Plans.md と実際の変更を照合可能に

設定不要—デフォルトで有効。

なぜ skill pack だけではなく Harness か？

skill pack はプロンプトを教えられます。Harness は実行時のふるまいまで強制します。

  • ガードレールエンジン が破壊的な書き込み、シークレット露出、force push 系を実行経路で止めます。
  • Hooks と review フロー が、実際に repo を触るツールの近くで品質確認を行います。
  • 検証スクリプトと evidence pack が、docs・配布物・/harness-work all の主張を再実行可能にします。

トラブルシューティング

問題 解決策
コマンドが見つからない まず /harness-setup を実行
Windows で harness-* コマンドが出ない プラグインを更新または再インストールしてください。公開 command skill は実ディレクトリで配布されるようになり、core.symlinks=false でも隠れなくなります。
プラグインが読み込まれない キャッシュをクリア: rm -rf ~/.claude/plugins/cache/claude-code-harness-marketplace/ して再起動
フックが動作しない Node.js 18+ がインストールされているか確認

詳しいヘルプは Issue を作成してください。

アンインストール

/plugin uninstall claude-code-harness

プロジェクトファイル（Plans.md、SSOT ファイル）はそのまま残ります。

Claude Code 2.1.74+ 対応機能

Harness は最新の Claude Code 機能をすぐに活用できます。

機能 スキル 用途
Agent Memory harness-work, harness-review セッション間の永続的な学習
TeammateIdle/TaskCompleted Hook breezing チームの自動監視
Worktree 分離 breezing 同一ファイルへの並列書き込みを安全化
HTTP hooks hooks Slack・ダッシュボード・メトリクスへの JSON POST
Effort levels + ultrathink harness-work 複雑なタスクに ultrathink を自動注入
Agent hooks hooks LLM によるコード品質ガード（secrets・TODO スタブ・セキュリティ）
${CLAUDE_SKILL_DIR} 変数 全 harness-* スキル スキル内参照の実行環境依存を排除
agent_id / agent_type フィールド hooks, breezing teammate 識別とロールガードを安定化
{"continue": false} teammate 応答 breezing 担当タスク完了時の自動停止
/reload-plugins 全 harness-* スキル スキル/フック編集を即時反映
/loop + Cron スケジューリング breezing, harness-work /loop 5m /sync-status による能動的ポーリング監視
PostToolUseFailure hook hooks ツール連続失敗 3 回で自動 escalation
Background Agent 出力修正 breezing run_in_background で出力パスが完了通知に含まれるように
Compaction 画像保持 全 harness-* スキル コンテキスト圧縮時に画像を保持
WorktreeCreate/Remove hook breezing Worktree ライフサイクルの自動セットアップ・クリーンアップ
modelOverrides 設定 harness-setup, breezing モデルピッカーの別名を Bedrock / Vertex などの実モデル ID にマッピング
autoMemoryDirectory 設定 session-memory, harness-setup Claude の auto-memory 保存先をプロジェクト単位で分離可能
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS hooks SessionEnd hook に cleanup / finalize 用の十分な時間を与える
完全な model ID 対応 agents-v3, breezing claude-sonnet-4-6 形式の model ID を frontmatter / JSON config で利用可能

全機能一覧: docs/CLAUDE-feature-table.md

ドキュメント

リソース 説明
Changelog バージョン履歴
Claude Code 互換性 動作要件
Distribution Scope 配布対象 / 互換維持 / 開発専用の境界
Work All Evidence Pack 成功系/失敗系の検証契約
Cursor 連携 2-Agent セットアップ
Benchmark Rubric static evidence と executed evidence の採点軸
Positioning Notes 公開向けの差別化メモ

コントリビュート

Issue と PR を歓迎します。CONTRIBUTING.md を参照。

謝辞

  • AI Masao — 階層的スキル設計
  • Beagle — テスト改ざん防止パターン

ライセンス

MIT License — 自由に使用、改変、商用利用可能。

English | 日本語