event-manual

ガイド 第48章

機械可読レイヤ

llms.txt・llms-full.txt・/api/registry（B2A）

このマニュアルサイトの読者は人間だけではない。レシピを実行するのは大半がコーディングエージェントであり（AGENTS.md の指示例 —「recipe add-surveys に従って実装せよ」）、エージェントにとって人間向け HTML の巡回は遅くて壊れやすい。そこで manual app はサイト機能として機械可読レイヤ（B2A 面 — business-to-agent）を持つ。これは特定パッケージの章ではなく、apps/manual 自身の設計の章である。

3つの公開面

URL形式役割
/llms.txttext（llms.txt 規約）入口 — サイト概要 + 主要ページの索引。エージェントが最初に読む1枚
/llms-full.txttext全文 — 全章・全レシピの本文をフラットに連結。1 fetch で全知識が入る
/api/registryJSON構造 — レシピ / 章 / モジュール / パッケージの一覧をプログラムで選別するための API

実装は Next.js の route handler 3 本:

  • apps/manual/src/app/llms.txt/route.ts
  • apps/manual/src/app/llms-full.txt/route.ts
  • apps/manual/src/app/api/registry/route.ts

llms.txt は「LLM がサイトを理解するための markdown 索引をルート直下に置く」という 2024 年提案の規約で、2026 年には主要クローラ・エージェントフレームワークが参照する事実上の標準になっている。人間の /sitemap に対する機械の対応物と考えればよい。llms-full.txt はその全文版 — コンテキスト窓が大きいエージェントは索引を辿るより全文を1回で取る方が速く確実、という運用実態に合わせた面である。

registry はデータから導出する — 手書き JSON を持たない

この3面の設計原則は1つ: 既存の単一真実源から純粋に導出し、独自のコンテンツを持たない。導出元は本サイトの中核データそのものである:

導出元内容
content/recipes/index.ts の RECIPES全レシピ（id / title / goal / prerequisites / features / chapters / ready / body）
content/index.ts の CHAPTERS公開済み全章（n / slug / title / packages / body）
content/modules-catalog.ts の MODULES選べる機能（key / pkg / status / enable / chapters）
content/packages-catalog.ts の PACKAGESパッケージ API 面（name / entry / exports）
lib/toc.ts の MANUAL_TOC部・章構成と published 状態

route handler はこれらを import して整形するだけで、registry 専用のマスタは存在しない。人間向けページ（/recipes / /guide / /modules / /reference）と機械向け3面が同じ配列を読むため、章を1本足せば両方に同時に載り、ドリフトが構造的に起きない。第42章の「中央配列を編集しない」（descriptor 自己記述）と同じ思想で、ここでは「公開面を増やしても登録点は増やさない」として効いている。

/api/registry の形は導出元の型がそのまま骨格になる（例）:

{
  "recipes":  [{ "id": "add-motion", "title": "…", "prerequisites": ["new-event"], "chapters": [47], "ready": true }],
  "chapters": [{ "n": 47, "slug": "motion-graphics", "title": "…", "packages": ["@event/motion"] }],
  "modules":  [{ "key": "networking", "pkg": "@event/networking", "status": "ready", "chapters": [32, 33, 34] }],
  "packages": [{ "name": "@event/motion", "entry": ["."], "exports": [{ "name": "Reveal", "desc": "…" }] }]
}

認証は無し（マニュアル自体が公開情報）、メソッドは GET のみ。サイトは知識面だけを提供し、実行（コード生成・配線）はエージェント側の clone で行う — 書き込み系を持たないので攻撃面も増えない。

エージェントの利用フロー — 1プロンプト生成の完成形

機械可読レイヤが埋めるのは「エージェントが URL しか知らない」状態から実装完了までの距離である:

  1. 発見 — GET /llms.txt（または /api/registry）で「何が選べて、どのレシピがあるか」を知る。

例:「イベントサイトに名鑑が欲しい」→ registry の modules から networking → recipe id add-networking を特定

  1. 取得 — レシピ本文を読む（/llms-full.txt 1 fetch、または該当レシピページ）。

レシピは自己完結ランブック（ファイルパス・完全コード・コマンド・検証）なので、これ以上の往復が要らない

  1. 実行 — エージェントがリポジトリを clone してレシピを上から実行する。

コード block は実装転写であり、@event/* import は recipe-lint が実 export と照合済み（第46章の系譜のドリフト対策）— 推測で書かれた API がレシピに存在しないことが CI で保証されている

  1. 検証 — レシピ末尾の検証節（typecheck / dev 確認）が完了条件そのもの。エージェントは「動いたか」を自分で判定できる

つまり「1プロンプトで実装できる」というこのリポジトリの中心主張は、(a) 自己完結レシピ、(b) lint による転写保証、(c) 機械可読な発見面、の3点で初めて閉じる。この章の面は (c) を担う。

AGENTS.md との関係 — 中と外

同じ役割のファイルがリポジトリ内にもある。AGENTS.md はリポジトリの中で作業するエージェントの入口（clone 済み・レシピ表とパッケージ表・鉄則）、llms.txt / registry はリポジトリの外から URL で来るエージェントの入口である:

AGENTS.mdllms.txt / llms-full.txt / api/registry
読者の位置clone 済み（ファイル直読み）URL しか知らない（HTTP fetch）
内容レシピ表・パッケージ表・鉄則・指示例同じ知識の公開射影 + 全文
更新手書き同期（レシピ表 + パッケージ表に各1行）データから自動導出（同期作業なし）

両者は同じ単一真実源の内向き / 外向きの2面であり、矛盾したら真実源（catalog / recipes / chapters のデータ）に合わせる。AGENTS.md だけが手書きなのは、鉄則や指示例のような「データにならない運用知」を含むためで、機械的に導出できる部分（表）は将来 registry からの生成に寄せられる余地がある。

自己増殖ループとの接続

メタレシピ add-new-module（このリポジトリに新モジュールを追加するプロトコル）の登録点 18 箇所のうち、manual 側の 7 箇所（recipe 本体 / recipes/index / chapter 本体 / content/index / toc / modules-catalog / packages-catalog）はすべて registry の導出元である。つまり:

> メタレシピに従ってモジュールを登録する → registry / llms.txt / llms-full.txt に自動で載る → 次のエージェントがそれを発見して1プロンプトで使う

登録がそのまま公開になり、公開がそのまま次の生成の入力になる。プラットフォームが自分の拡張手順を機械可読で配り、その手順の実行結果がまた機械可読面に現れる — この閉ループが「マシンプラットフォーム」という章題の意味である。

関連 — この章から動かす

実装レシピadd-new-module