YACHI AGENT TEAMS HARNESS

ハーネスの操作と効果

AI に「どう作るか」を毎回説明しなくてよくする開発基盤。
操作は少なく、品質・再現性・学習の効果を固定する。

操作

キックオフ → /project-manager → 確認だけ

効果

設計・実装・テスト・レビューが自動で直列実行

成果

同じ規約のアプリが、プロジェクトをまたいで揃う

1枚で見る全体像

人がやること / ハーネスがやること

人がやること（操作）ハーネスが返すもの（効果）
やりたい機能を日本語で伝える設計仮説 → 実装 → テスト → レビューまで分解
キックオフでモデル・DB・キーを選ぶ以後の全エージェントが同じ前提で動く
設計サマリを「はい」で承認する承認なしではコードを書かない（手戻り防止）
v3 テンプレから新規リポを切る規約・RR・エージェント体制が最初から入る
任意で telemetry-enroll件数だけ母リポに集まり、次の標準機能になる
リポジトリの使い分け

母リポと開発者テンプレ

母リポ（このリポ）

  • ハーネス自体を進化させる場所
  • テレメトリ受信・/harness 管理画面
  • RR 昇格の週次 PR

yachi-original-harness-v3

  • アプリ開発の起点（Use this template）
  • 規約・エージェント・RR は母と同じ
  • 学習インフラは除いてある（軽い）

母で直した規約は generate-developer-template で v3 に再生成する。v3 でハーネス本体を直しても母には自動では戻らない。

開始操作

プロジェクトの立ち上げ

1. v3 をテンプレ作成→ 2. setup / kickoff→ 3. /project-manager→ 4. 「はい」で設計開始
操作効果
setup.ps1 で名前と slugWorker名・DB名・コンテナ名が一括で揃う
kickoff.ps1 でモデル / DB / キー設計前の聞き漏れをなくす
pnpm run setup + devDocker Postgres + Vite + Wrangler が起動
チャットで機能を1文伝えるPM が工程全体を回す。工程ごとに「次どうする？」と聞かない
日常の開発操作

1機能が通るパイプ

PM→ 設計→ 設計レビュー→ 実装×3→ tester→ reviewer

操作（人が止める点）

  • Step 0 の解釈確認
  • 全体設計 / 詳細設計の承認
  • 3回直しても直らないときだけ選択

効果（自動）

  • Schema → API → UI の依存順を守る
  • テスト欠落・規約違反は差し戻し
  • 権限・日本語 UI・cursor ページングを既定適用
チーム編成

8体の役割とモデル

役割モデル効果
project-managerOpus 5計画の一貫性。他エージェントを直接呼ばせない
architectOpus 5システム全体の設計。実装しない
architect-moduleSonnet 5モジュール詳細（DB/API/UI）
design-reviewerOpus 5過剰設計を実装前に落とす
developerSonnet 5実装と Phase A テスト作成
testerHaikuテスト実行。欠落は FAIL
reviewerOpus 5品質 / セキュリティ / FE / UI の最終判定
package-researcherSonnet 5新規パッケージは評価→承認後に入れる
品質の効果

毎回同じミスをさせない絶対ルール

画面・データ

  • fetch は TanStack Query のみ
  • フォームは React Hook Form + Zod
  • UI は shadcn。confirm/alert 禁止
  • 表示文言は日本語

安全・権限

  • 権限は middleware。インライン判定禁止
  • 秘密情報はチャットに貼らない
  • スキーマ削除・DB 破壊は禁止
  • Account ID は wrangler.toml 先頭で固定

効果: プロジェクトが変わっても「作り方」が同じ。レビュー指摘が減り、後工程の手戻りが減る。

RR = Recurring Requirements

一覧を「毎回お願い」しなくてよい

adopted の共通要件は、該当画面なら黙って入る。

RR-1〜3

件数セレクタ、固定ページャ、検索条件の URL 保持

RR-4〜8

CSV、権限、詳細検索、列ソート / 幅

RR-9〜11

検索付きドロップダウン、一括操作、論理削除

操作: カタログに載せるのは人間の承認だけ。
効果: 次のプロジェクトから標準機能になる。ただし一覧は重い（速度の主因）。

学習ループ

使えば使うほど、次が速くなる

層操作効果
ローカルいつもどおり開発するだけプロンプトが件数分類される（本文は出ない）
横断（任意）v3 で telemetry-enroll複数プロジェクトの同じ要望が母に見える
昇格母リポで候補 PR をレビューRR として全テンプレに入る

v3 を切っただけでは母には集まらない。enroll がオンのときだけ件数を送る。

速度

遅い理由と、速くする操作

遅くなる理由

  • 設計必須 + 承認待ち
  • 実装 3 タスク直列
  • 一覧に RR-1〜11 全適用
  • tester + reviewer 最大 3 周

速くする操作

  • 「この機能は MVP。RR は最小」と明示
  • 参照実装コピーは Simple CRUD 扱い
  • 実装モデル試験は developer だけ
  • 納品前に delivery（E2E + 全 RR）へ上げる
ローカルと本番

開発環境の操作

操作効果
pnpm run devDocker の Postgres + Vite :5173 + Wrangler :8787
DATA_MODE=mockDB なしで画面を組める（接続 0）
DATA_MODE=db + seedローカル Postgres で CRUD を検証
本番は Hyperdrive → SupabaseDocker の DB とは別物。migrate は API 経由

React / Hono は Docker でも動く。差分は Hyperdrive・R2・Cron・同一オリジン配信。そこは Cloudflare で確認する。

デプロイ操作

Cloudflare は toml の account_id に固定

操作

  • wrangler.toml 先頭に 32 桁の Account ID
  • deploy-setup-form でトークン類を登録
  • deploy-check で ERROR=0
  • deploy-local -Env staging|production

効果

  • 複数 CF アカウントでも取り違えない
  • 環境変数の Account ID は使わない
  • Worker / Hyperdrive / R2 が同じ口座へ行く
  • 本番ゲート（push 承認 + Environment）
使い分け

目的でテンプレと厚さを選ぶ

目的操作効果
アプリ・PoC を作るv3 テンプレ + 「MVP」指定最短で画面が動く
ハーネス自体を直す母リポで改修 → generate-developer-template全子プロジェクトに還元
顧客納品delivery（全 RR + E2E + reviewer 4 トラック）チェックリストが埋まってから出す
横断学習v3 + telemetry-enroll要望が母の RR 候補になる
まとめ

覚える操作は少ない

始める

v3 を切る → kickoff → /project-manager → はい

作る

機能を1文で伝える。承認点以外は止めない

出す

toml の account_id を確認 → deploy-check → deploy-local

効果の本体は「速さ」ではなく、同じ品質の作り方を、人が覚えなくても繰り返せること。

1 / 14