Quartz 4

AGENTS.md とハーネスでナレッジを広げる設計

9 min read

AGENTS.md とハーネスでナレッジを広げる設計

要旨

claude-code や codex のようなコーディングエージェントを「obsidian vault に対して書き込む執筆者」として使うとき、[[agents-md]] とハーネスの設計がナレッジの拡がりを決める。 鍵は 「重要概念に出会ったら必ず [[wikilink]] を張り、リンク先が無ければスタブを作る」というルールをエージェントに機械的に守らせること。 これによりノートを1本書くたびに ナレッジグラフの周辺ノードが増え、ユーザーの知識地図が能動的に拡張されていく。 本稿ではその AGENTS.md の書き方、ハーネス側で支える仕組み、運用上の注意点を整理する。

背景・動機

個人のナレッジベースを Obsidian + デジタルガーデン (Quartz) で運用するとき、最大のボトルネックは「人間が手で書ける量」である。 LLM エージェントに調査記事の生成を任せたいが、放っておくと:

  • ノートが孤立して ツェッテルカステン的なネットワーク効果が出ない
  • 関連概念へのリンクが張られず、グラフビューが過疎になる
  • 同じ概念に異なる表記が乱立してリンク切れが起きる

これらは「エージェントへの指示が曖昧」「リポジトリ側の規約が文書化されていない」ことに起因する。 解決策が [[agents-md]] (instruction file) とハーネス (実行環境側の制約) の組み合わせである。

調査内容

AGENTS.md の役割

[[agents-md]] はエージェントが作業前に読み込む「リポジトリ憲法」。 claude-code では CLAUDE.md、codex では AGENTS.md という慣習があるが、内容は同じ目的を果たす:

  1. 作業範囲の境界: 何を触ってよく、何を触ってはいけないか
  2. 命名・配置の規約: ファイル名、ディレクトリ、frontmatter
  3. 出力スタイル: 見出し階層、記法、トーン
  4. チェックリスト: 提出前の self-review 項目

LLM は「曖昧な目的」より「具体的な手続き」に強い。 規約をチェックリスト形式で書くと従順度が大きく上がる。

ハーネスの役割

ハーネスとはエージェントが動く実行環境のこと。具体的には:

  • 設定ファイル (settings.json, .claude/, .codex/)
  • フック (PreToolUse, PostToolUse などで自動検証)
  • スラッシュコマンド (頻出操作のショートカット)
  • 権限・許可リスト (危険な操作のガード)
  • コンテキスト注入 (CLAUDE.md / AGENTS.md の自動ロード)

AGENTS.md は「読まれる文書」、ハーネスは「強制される機構」。 両者は相補的で、どちらかだけでは漏れる。

役割AGENTS.mdハーネス
ファイル名規約文書化フックで命名検証も可
frontmatter 必須項目文書化フックで欠落検出
設定ファイルへの書き込み禁止文書化権限拒否で物理的に防ぐ
ビルド実行「人間がやる」と明記許可リストから外す

ナレッジ構築用 AGENTS.md の設計原則

1. 機械的に実行可能な手順に落とす

「重要概念にはリンクを張る」だけでは LLM は判断ブレが大きい。次のように手順化する:

  1. 本文に概念が登場したら content/topics/ と content/investigations/ を走査する
  2. 既存ノートがあれば [[wikilink]] に変換する
  3. 無く、かつ重要なら topics/ にスタブを作って frontmatter ＋ ## 概要 だけ書く
  4. 該当トピックハブの ## 関連調査 に今回のノートへのリンクを追記する

これによりウィキリンクの網が1記事書くごとに必ず広がる。

2. スタブを許容する

「中身が無いノートを作るな」というルールはグラフ拡張を阻害する。 逆に 空でいいから先にスタブを作れ と命じることで、後から人間が肉付けできる「未来の入口」が増える。 これは ツェッテルカステンの「Folgezettel」発想に近い。

3. 公開状態を人間ゲートにする

エージェントが書いたノートは原則 draft: true で出し、人間レビュー後に false へ。 ハーネス側で draft: false を勝手に書き換えないよう許可リストを絞ると安全。

4. ファイル名に時刻順を埋め込む

YYYY-MM-DD-NN-スラッグ.md のように、1日に複数記事を書く前提で連番を持つ。 これは「エージェントによる大量生成」というワークフロー特有の要請で、人間が手書きする前提のノート命名（タイトルそのまま）とは異なる。

1記事を書くたびに以下が起きる:

graph LR
  A[新規記事] -->|登場概念| B{既存トピック?}
  B -->|あり| C[既存ハブに追記]
  B -->|なし| D[スタブ作成]
  C --> E[ハブのバックリンク増]
  D --> F[未開拓領域の入口]
  E --> G[グラフビューで濃淡発見]
  F --> G
  G --> H[次の調査テーマ発見]
  H --> A

エージェントは「リンク張れ」と命じられているだけだが、結果としてユーザーの知識地図が 書けば書くほど周辺領域に伸びていく。 これは古典的な ツェッテルカステンのデジタル実装であり、Andy Matuschak 流の Evergreen Notes、[[digital-garden]] 思想とも整合する。

ハーネス側で支える具体例

claude-code の場合:

  • .claude/settings.json の permissions: quartz.config.ts への Edit を拒否リストに入れる
  • PostToolUse フック: .md ファイルが書かれた直後に frontmatter linter を走らせる
  • スラッシュコマンド /note <slug>: 連番採番 + テンプレート展開を1コマンド化
  • PreToolUse フック: ファイル名が YYYY-MM-DD-NN-*.md パターンに合っているか検証

codex の場合:

  • .codex/config.toml で書き込み可能パスを content/**/*.md に限定
  • AGENTS.md が自動ロードされる仕組みに乗せる

失敗パターン

要検証だが、運用していて見える失敗:

  • AGENTS.md が長すぎる: LLM のコンテキストを食う上に守られなくなる。500〜800行が現実的上限
  • 規約が抽象的: 「適切にリンクする」では機能しない。手順に落とす
  • ハーネスが緩い: AGENTS.md で禁止しただけでは事故る。物理的に止める
  • スタブが氾濫して空ノートばかり: 月次で人間が剪定する儀式が要る

結論

[[agents-md]] は「文書化された規約」、ハーネスは「強制機構」。 両者を 「wikilinks を張れば張るほどナレッジが広がる」というインセンティブ設計 に揃えると、エージェント執筆が単なる量産ではなくユーザーの知識ネットワーク拡張の駆動力になる。

次のアクション:

  • 本リポジトリの AGENTS.md にすでに組み込み済みの規約が、実運用で守られているかを数記事書いた後に検証する
  • ハーネス側 (.claude/ 設定、フック) の整備は別タスクとして起票する（要検証: フックでの frontmatter 検証スクリプトの実装難度）
  • スタブが空のまま放置される閾値（例: 30日空のままなら通知）を運用ルールに追加するか検討

関連

出典

（本稿は実装経験と公開ドキュメントからの一般論で構成。一次情報源は未引用のため、断定箇所は「要検証」と明記している。引用すべき出典が見つかれば content/refs/ に追加する）

Graph View

Backlinks