Agent-almanac build-coherence

install
source · Clone the upstream repo
git clone https://github.com/pjt222/agent-almanac
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/ja/skills/build-coherence" ~/.claude/skills/pjt222-agent-almanac-build-coherence-5cf9f4 && rm -rf "$T"
manifest: i18n/ja/skills/build-coherence/SKILL.md
source content

一貫性の構築

独立した評価、明示的な声に出しての推論による提唱、確信度校正されたコミットメント閾値、構造化されたデッドロック解決を通じて競合するアプローチを評価する — 複数の推論パスから一貫した決定を生成する。

使用タイミング

  • forage-solutions
    が複数の有効なアプローチを特定し、選択が必要な時
  • 2つのアプローチ間で揺れてどちらにもコミットできない時
  • 構造化された推論で決定を正当化する必要がある時(アーキテクチャ選択、ツール選択、実装戦略)
  • 以前の決定が直感で行われ、エビデンスベースの検証が必要な時
  • 内部推論が矛盾する結論を生み出し、一貫性を回復する必要がある時
  • 不可逆的なアクション(マージ、デプロイ、削除)の前で、誤った選択のコストが高い時

入力

  • 必須: 評価する2つ以上の競合するアプローチ
  • 任意: 事前の偵察からの品質評価(
    forage-solutions
    を参照)
  • 任意: 決定のステークス(可逆、中程度、不可逆)(閾値校正用)
  • 任意: 決定のための時間予算
  • 任意: 既知の失敗モード(揺れ、早すぎるコミットメント、集団思考)

手順

ステップ1: 独立評価

比較する前に、各アプローチをそれ自体のメリットで評価する。重要なルール: アプローチAの評価がアプローチBの評価にバイアスをかけてはならない。

各アプローチを独立に評価する:

Approach Evaluation Template:
┌────────────────────────┬──────────────────────────────────────────┐
│ Dimension              │ Assessment                               │
├────────────────────────┼──────────────────────────────────────────┤
│ Approach name          │                                          │
├────────────────────────┼──────────────────────────────────────────┤
│ Core mechanism         │ How does this approach solve the problem? │
├────────────────────────┼──────────────────────────────────────────┤
│ Strengths (2-3)        │ What does this approach do well?          │
├────────────────────────┼──────────────────────────────────────────┤
│ Risks (2-3)            │ What could go wrong? What is assumed?     │
├────────────────────────┼──────────────────────────────────────────┤
│ Evidence quality        │ How well-supported is this approach?      │
│                        │ (verified / inferred / speculated)        │
├────────────────────────┼──────────────────────────────────────────┤
│ Quality score (0-100)  │ Overall assessment                        │
├────────────────────────┼──────────────────────────────────────────┤
│ Confidence (0-100)     │ How confident in this assessment?         │
└────────────────────────┴──────────────────────────────────────────┘

これを各アプローチに別々に記入する。すべての個別評価が完了するまで比較を書かない。

期待結果: 各アプローチがそれ自体の条件で評価された独立した評価。アプローチBの評価がアプローチAを参照しない。品質スコアはランキングではなく真の評価を反映する。

失敗時: 評価が汚染されている場合(Bを評価しながら「Aより良い」と書いている)、リセットする。Aを完全に評価し、次にフレーミングをクリアしてBをゼロから評価する。スコアがすべて同じ場合、評価の次元が粗すぎる — ドメイン固有の基準を追加する。

ステップ2: ワグルダンス — 声に出して推論する

各アプローチをその品質に比例して提唱する。これはミツバチのワグルダンスのAI等価物: 暗黙の推論を明示的かつ公開的にする。

  1. 各アプローチについて、懐疑的なユーザーに提示するかのようにケースを述べる:
    • 「アプローチAは[エビデンス]のため強い。主なリスクは[リスク]で、[緩和策]によって緩和される。」
  2. 提唱の強度は品質スコアに比例すべき:
    • 高品質アプローチ: 具体的なエビデンスを伴う詳細な提唱
    • 中品質アプローチ: 認識された制限を伴う簡潔な提唱
    • 低品質アプローチ: 完全性のために言及、積極的には提唱しない
  3. 相互検査: Aを提唱した後、代わりにBを支持するエビデンスを積極的に探す。Bを提唱した後、Aを支持するエビデンスを探す。これが確証バイアスに対抗する

声に出して推論する目的は、決定を監査可能にすること — 自分自身とユーザーに対して。推論が明確にできない場合、評価はスコアが示唆するよりも浅い。

期待結果: 中立的な観察者にとって説得力のある各アプローチの明示的な推論。相互検査が当初見落とされていた少なくとも1つの考慮事項を明らかにする。

失敗時: 提唱が形式的に感じられる場合(形だけ)、アプローチが真に異なっていない可能性がある — 同じアイデアのバリエーションかもしれない。確認する: アプローチはメカニズムで異なるか、実装の詳細のみか? 後者の場合、決定はそれほど重要ではないかもしれない — どちらかを選んで進む。

ステップ3: 定足数閾値の設定とコミット

コミットに必要な確信度閾値を設定し、決定のステークスに校正する。

Confidence Thresholds by Stakes:
┌─────────────────────┬───────────┬──────────────────────────────────┐
│ Decision Type       │ Threshold │ Rationale                        │
├─────────────────────┼───────────┼──────────────────────────────────┤
│ Easily reversible   │ 60%       │ Cost of trying and reverting is  │
│ (can undo)          │           │ low. Speed matters more than     │
│                     │           │ certainty                        │
├─────────────────────┼───────────┼──────────────────────────────────┤
│ Moderate stakes     │ 75%       │ Reverting has cost but is        │
│ (costly to reverse) │           │ possible. Worth investing in     │
│                     │           │ evaluation                       │
├─────────────────────┼───────────┼──────────────────────────────────┤
│ Irreversible or     │ 90%       │ Cannot undo. Must be confident.  │
│ high-stakes         │           │ If threshold not met, gather     │
│                     │           │ more information before deciding │
└─────────────────────┴───────────┴──────────────────────────────────┘
  1. 決定のステークスを分類する
  2. 確認する: リーディングアプローチの品質スコア × 確信度が閾値に達するか?
  3. はいの場合: コミットする。決定、推論、受け入れる主要リスクを述べる
  4. いいえの場合: 確信度を閾値まで上げる追加情報を特定する
  5. コミットしたら、新しい失格エビデンスが出ない限り再訪しない

期待結果: 述べられた推論を伴う明確なコミットメントの瞬間。決定がそのステークスに適した確信度レベルで行われる。

失敗時: 閾値に到達しない場合(不可逆的な決定で90%に達しない)、問う: 決定は本当に不可逆的か? 可逆的なテストフェーズ + 不可逆的なコミットに分解できるか? 一見不可逆的な決定のほとんどは段階的にできる。段階化が不可能な場合、不確実性をユーザーに伝えてガイダンスを求める。

ステップ4: デッドロックの解決

2つ以上のアプローチが類似のスコアを持ち、いずれの単一アプローチにも定足数閾値が達成されない時。

Deadlock Resolution:
┌────────────────────────┬──────────────────────────────────────────┐
│ Deadlock Type          │ Resolution                               │
├────────────────────────┼──────────────────────────────────────────┤
│ Genuine tie            │ The approaches are equivalent. Pick one  │
│ (scores within 5%)     │ and commit. The cost of deliberating     │
│                        │ exceeds the cost of picking the "wrong"  │
│                        │ equivalent option. Flip a coin mentally  │
├────────────────────────┼──────────────────────────────────────────┤
│ Information deficit    │ The tie exists because evaluation is     │
│ (scores uncertain)     │ incomplete. Invest one more specific     │
│                        │ investigation — a targeted file read, a  │
│                        │ quick test — then re-score               │
├────────────────────────┼──────────────────────────────────────────┤
│ Oscillation            │ Scoring keeps flip-flopping depending on │
│ (scores keep changing) │ which dimension gets attention. Time-box:│
│                        │ set a timer, evaluate once more, commit  │
│                        │ to the result regardless                 │
├────────────────────────┼──────────────────────────────────────────┤
│ Approach merge         │ The best parts of A and B can be         │
│ (compatible strengths) │ combined. Check for compatibility. If    │
│                        │ merge is coherent, use it. If forced,    │
│                        │ don't — pick one                         │
└────────────────────────┴──────────────────────────────────────────┘

期待結果: 適切なメカニズムによりデッドロックが解決される。解決は決定的 — 実行を損なう残りの疑念がない。

失敗時: すべての解決戦略を通じてデッドロックが持続する場合、決定が時期尚早かもしれない。ユーザーに問う: 「同等に強い2つのアプローチがあります: [A]と[B]。[各の簡潔なケース。] あなたの優先事項にどちらがより合っていますか?」真の引き分けをユーザーに委任するのは失敗ではない — 決定がAIが推測できない価値観に依存することを認めること。

ステップ5: 一貫性の品質評価

決定にコミットした後、プロセスが真の一貫性を生んだのか単なる決定を生んだのか評価する。

  1. 決定はエビデンスベースだったか、それとも初期の好みをゴム印したものか?
    • テスト: 評価前後で好みは同じだったか? そうなら、評価は何かを変えたか?
  2. 敗退したアプローチは真に考慮されたか、それともストローマンだったか?
    • テスト: 敗退したアプローチの最も強いケースを明確にできるか?
  3. 再評価をトリガーするシグナルは何か?
    • 決定を無効にする具体的な観察を定義する(「APIがXをサポートしないことが分かれば、アプローチBの方が良くなる」)
  4. 敗退したアプローチから、実装に情報を提供すべき有用な情報はあるか?
    • アプローチBで特定されたリスクはアプローチAにも適用される可能性がある

期待結果: 決定を確認するか弱いと特定する簡潔な品質チェック。弱い場合、不安定な基盤の上で進むのではなく、適切な以前のステップに戻る。

失敗時: 品質チェックが決定がエビデンスベースではなく好みベースだったことを明らかにした場合、正直に認める。好みしか利用できないこともある — ただし、分析として装うのではなく、そのようにラベル付けすべき。

バリデーション

  • 比較前に各アプローチが独立に評価された
  • 提唱がメリットに比例していた(メリットに関係なく均等な注目ではない)
  • 提唱後に相互検査が実行された(反証エビデンスの探索)
  • 定足数閾値が決定のステークスに校正された
  • デッドロックの場合、具体的な解決戦略が適用された
  • 決定後の品質チェックが実行された
  • 再評価トリガーが定義された

よくある落とし穴

  • 早すぎるコミットメント: すべてのアプローチを評価する前に決定する。最初に考慮されたアプローチはアンカリング優位を持つ — 最初であるというだけでより多くの精神的注目を得る。比較する前にすべてを評価する
  • 不均等なアプローチへの均等な提唱: アプローチAが85点、アプローチBが45点の場合、両方に均等な時間を費やすのは努力の無駄であり、偽りの等価性を生む
  • ゴム印: すでに行われた決定を正当化するために評価プロセスを経ること。テストは評価が結果を変えられたかどうか。できなかった場合、プロセスは茶番
  • 閾値回避: 適切な閾値を満たすために必要な情報を集めるのではなく、決定を容易にするために確信度閾値を下げる
  • 敗退側の無視: 敗退したアプローチは勝利したアプローチに適用される警告を含むことが多い。アプローチBで特定されたリスクはアプローチAが選ばれたからといって消えない

関連スキル

  • build-consensus
    — このスキルが単一エージェント推論に適応したマルチエージェントコンセンサスモデル
  • forage-solutions
    — 一貫性が評価するソリューション空間を偵察する; 通常このスキルの前に実行
  • coordinate-reasoning
    — マルチパス評価中の情報フローを管理する
  • center
    — 偏りのない評価に必要なバランスの取れたベースラインを確立する
  • meditate
    — 異なるアプローチの評価間で前提をクリアする