Agent-almanac observe

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/observe" ~/.claude/skills/pjt222-agent-almanac-observe-2e4221 && rm -rf "$T"
manifest: i18n/ja/skills/observe/SKILL.md
source content

観察

構造化された観察セッションを実施する — 観察対象のフレーミング、持続的な中立的注意による目撃、解釈なしのパターン記録、発見の分類、パターンからの仮説生成、将来の参照のための観察のアーカイブ。

使用タイミング

  • システムの挙動が不明確で、観察なしの行動が時期尚早な時
  • 原因不明の問題をデバッグする時 — 介入前の観察が症状の隠蔽を防ぐ
  • コードベースやシステムが変更され、さらなる変更前にその影響を目撃する必要がある時
  • 将来のインタラクションを改善するために会話を通じてユーザーの行動パターンを理解する時
  • バイアス、習慣、または繰り返しのエラーについて自身の推論パターンを監査する時
  • learn
    がモデルを構築した後、実際のシステムの観察を通じてそのモデルを検証する必要がある時

入力

  • 必須: 観察対象 — 観察するシステム、コードベース、行動パターン、ユーザーインタラクション、または推論プロセス
  • 任意: 観察の期間/範囲 — 結論を出すまでにどのくらいの時間または深さで観察するか
  • 任意: 観察の焦点を導く特定の質問または仮説
  • 任意: 比較のための過去の観察(時間経過による変化の検出)

手順

ステップ1: フレーム — 観察の焦点を設定する

何を観察しているか、なぜか、どの視点からかを定義する。

Observation Protocol by System Type:
┌──────────────────┬──────────────────────────┬──────────────────────────┐
│ System Type      │ What to Observe          │ Categories to Watch      │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ Codebase         │ File structure, naming   │ Patterns, anti-patterns, │
│                  │ conventions, dependency  │ consistency, dead code,  │
│                  │ flow, test coverage,     │ documentation quality,   │
│                  │ error handling patterns  │ coupling between modules │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ User behavior    │ Question patterns,       │ Expertise signals, pain  │
│                  │ vocabulary evolution,    │ points, unstated needs,  │
│                  │ repeated requests,       │ learning trajectory,     │
│                  │ emotional signals        │ communication style      │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ Tool / API       │ Response patterns, error │ Rate limits, edge cases, │
│                  │ conditions, latency,     │ undocumented behavior,   │
│                  │ output format variations │ state dependencies       │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ Own reasoning    │ Decision patterns, tool  │ Biases, habits, blind    │
│                  │ selection habits, error  │ spots, strengths,        │
│                  │ recovery approaches,     │ recurring failure modes, │
│                  │ communication patterns   │ over/under-confidence    │
└──────────────────┴──────────────────────────┴──────────────────────────┘
  1. 観察対象を選択し、明示的に名前を付ける
  2. 観察の境界を定義する:何が含まれ、何が範囲外か
  3. 観察の姿勢を宣言する:「私は観察しているのであり、介入しているのではない」
  4. 導く質問がある場合は述べる — ただし軽く保持する;質問の範囲外のことに気づく意思を持つ
  5. 上記のマトリクスから適切なカテゴリーを選択する

期待結果: 注意を制約せずに方向付ける明確なフレーム。観察者はどこを見るべきか、観察をどのカテゴリーに分類するかを知っているが、予想外のことに対して開かれている。

失敗時: 観察対象が広すぎる場合(「すべてを観察する」)、1つのサブシステムまたは1つの行動パターンに絞る。対象が狭すぎる場合(「この1つの変数を観察する」)、周囲のコンテキストにズームアウトする — 興味深いパターンは多くの場合、端にある。

ステップ2: 目撃 — 持続的な中立的注意

解釈、判断、介入なしに観察対象に注意を向け続ける。

  1. 体系的な観察を開始する:ファイルを読む、実行パスを追跡する、会話履歴をレビューする — 対象が必要とするものを行う
  2. 見えたものを記録する。それが何を意味するかではない — 解釈の前に記述
  3. 観察中に遭遇した問題をすぐに修正したい衝動に抵抗する — メモして続ける
  4. 十分な観察が蓄積される前にパターンを説明したい衝動に抵抗する
  5. 注意が別の対象に逸れた場合、その逸れを記録し(意味があるかもしれない)、フレームに戻る
  6. 定義された期間、観察を維持する:分類に移る前に少なくとも3-5の異なるデータポイント

期待結果: 生の観察の集合 — 具体的で、具象的で、解釈を含まない。観察はフィールドノートのように読める:「ファイルXはYをインポートしているが関数Zを使用していない。ファイルAは300行;ファイルBは30行で同様の機能をカバーしている。」

失敗時: 観察がすぐに分析を引き起こす場合(「これは…だから間違っている」)、分析的習慣が観察の姿勢を上書きしている。意識的にフェーズを分離する:観察を事実として書き、次に解釈を「仮説」とラベル付けした別のメモとして書く。中立性が不可能な場合(観察したものに対する強い反応)、反応自体をデータとして記録する:「Xを観察した時に強い懸念を感じた — これは重大な問題を示しているかもしれないし、私のバイアスを示しているかもしれない。」

ステップ3: 記録 — 生のパターンをキャプチャする

観察が新鮮なうちに構造化された形式に書き写す。

  1. 各観察を事実の単一の文として列挙する(何が見えたか、どこで、いつ)
  2. 自然に類似した観察をグループ化する — グループ化を強制せず、観察がクラスター化する時に気づく
  3. 頻度を記録する:このパターンは1回、時々、それとも広範に出現したか?
  4. 対比を記録する:パターンはどこで破れたか?例外は多くの場合、ルールよりも有益である
  5. 時間的パターンを記録する:観察は時間とともに変化したか、それとも静的だったか?
  6. 正確な証拠をキャプチャする:ファイルパス、行番号、具体的な言葉、具体例

期待結果: 5-15の個別の観察の構造化された記録で、それぞれに具体的な証拠がある。記録は、別の観察者が各観察を独立して検証できるほど詳細であるべき。

失敗時: 観察が抽象的すぎる場合(「コードが散らかっているように見える」)、具体性で根拠付ける必要がある — どのファイル、どのパターン、何が散らかっているのか?観察が粒度が細かすぎる場合(「47行目でブレースの前にスペースがある」)、パターンレベルにズームアウトする — これは1回限りか、体系的な問題か?

ステップ4: 分類 — 発見を整理する

まだ説明せずに、観察を意味のあるカテゴリーに分類する。

  1. 記録されたすべての観察をレビューし、自然なグループを探す
  2. 各観察をステップ1のマトリクスのカテゴリーに割り当てるか、必要に応じて新しいカテゴリーを作成する
  3. 各カテゴリー内で、頻度と重要性によって観察をランク付けする
  4. 多くの観察があるカテゴリー(十分に文書化された領域)と少ないカテゴリー(潜在的な盲点)を特定する
  5. カテゴリー横断のパターンを探す:同じ根本的なパターンが異なるカテゴリーで異なる形で現れているか?
  6. どのカテゴリーにも当てはまらない観察を記録する — 外れ値は多くの場合、最も興味深いデータである

期待結果: 明確なグループを持つ分類された観察マップ。各カテゴリーにはそれを裏付ける具体的な観察がある。マップはパターンとギャップの両方を示す。

失敗時: 分類が無理やりに感じる場合、観察には自然なグループがないかもしれない — それ自体が発見である(システムに一貫した構造が欠けているかもしれない)。すべてが1つのカテゴリーにきれいに収まる場合、観察の範囲が狭すぎた — ズームアウトする。

ステップ5: 理論化 — パターンから仮説を生成する

ここで — そしてここで初めて — 観察の解釈を始める。

  1. 観察された各主要パターンについて、仮説を提案する:「このパターンが存在するのは…だからである」
  2. 各仮説について、観察からの裏付け証拠を特定する
  3. 各仮説について、それを反証する反証がどのようなものかを特定する
  4. 説明力によって仮説をランク付けする:どれが最も多くの観察を説明するか?
  5. 少なくとも1つの逆張り仮説を生成する:「明白な説明はXだが、Yである可能性もある。なぜなら…」
  6. どの仮説が検証可能で、どれが推測的かを特定する

期待結果: 主要パターンを説明する2-4の仮説で、それぞれが具体的な観察で裏付けられている。少なくとも1つの仮説は驚くべき、または逆張りであるべき。観察と解釈の区別が維持されている — どの部分がデータでどの部分が理論かが明確。

失敗時: 仮説が形成されない場合、観察にはさらに蓄積する時間が必要かもしれない — ステップ2に戻る。仮説が多すぎる場合(すべてが「おそらく」)、最も強い証拠を持つ2-3を選択し、残りを保留にする。明白な仮説のみが形成される場合、逆張りの見方を強制する:「逆が真だとしたら?」

ステップ6: アーカイブ — パターンライブラリを保存する

将来の参照のために観察と仮説を保存する。

  1. 主要な発見を要約する:証拠付きの3-5のパターン
  2. 主要な仮説とその信頼度を述べる
  3. 観察されなかったもの(潜在的な盲点)を記録する
  4. 仮説を強化または弱化するフォローアップ観察を特定する
  5. パターンが永続的な場合(セッション間で関連性がある)、MEMORY.mdの更新を検討する
  6. 観察にコンテキストをタグ付けする:いつ行われたか、何がきっかけだったか、どの範囲がカバーされたか

期待結果: 将来の観察セッションが積み重ねることができるアーカイブ。アーカイブは観察(データ)と仮説(解釈)を明確に区別する。信頼度とギャップについて正直である。

失敗時: 観察がアーカイブに値しないと感じる場合、浅すぎたかもしれない — または本当にルーチン的なものかもしれない(すべての観察セッションが洞察を生むわけではない)。ネガティブな結果もアーカイブする:「Xを観察し異常は見つからなかった」は有用な将来のコンテキストである。

バリデーション

  • 観察が始まる前に観察フレームが設定された(自由形式の探索ではない)
  • 生の観察が解釈の前に事実として記録された
  • 具体的な証拠を持つ少なくとも5つの個別の観察がキャプチャされた
  • 解釈(仮説)が観察(データ)から明確に分離された
  • 少なくとも1つの驚くべき、または逆張りの発見が生成された
  • アーカイブされた記録は、別の観察者が検証できるほど具体的である

よくある落とし穴

  • 早すぎる介入: 問題を見つけてすぐに修正し、それが属するより広いパターンを理解する機会を失う
  • 観察バイアス: 存在するものではなく期待されるものを見る。期待は知覚をフィルタリングする — ステップ1のクリアリングステップはこれを軽減するが排除はしない
  • 分析麻痺: 行動に移ることなく際限なく観察し続ける。時間またはデータポイントの制限を設定し、結論を出すことにコミットする
  • 物語の押し付け: つながりが弱い場合でも観察をつなぐストーリーを構築する。すべての観察が一貫したナラティブを形成するわけではない — 断片的な発見は有効である
  • 馴染みと理解の混同: 「これを前に見たことがある」は「これがなぜここにあるか理解している」と同じではない。以前の接触は偽りの確信を生み出す可能性がある
  • 自身の反応の無視: 観察に対する観察者の感情的または認知的反応はデータである。システムに対する混乱、退屈、または警戒の感覚には多くの場合、本当のシグナルが含まれている

関連スキル

  • observe-guidance
    — 体系的な観察を人にコーチングするための人間ガイダンスのバリアント
  • learn
    — 観察はモデル構築のための生データを提供することで学習に供給する
  • listen
    — ユーザーシグナルへの外向きの注意;観察はあらゆるシステムへのより広い範囲の注意
  • remote-viewing
    — 体系的な観察を通じて検証できる直感的探索
  • meditate
    — 観察が必要とする持続的注意力を発達させる
  • awareness
    — 脅威に焦点を当てた状況認識;観察は防御駆動ではなく好奇心駆動