drift

Drift

drift は Markdown ドキュメントをコードに紐付け、古くなっていないかを検査します。

エージェントにとって重要な理由

コードを変更しても、その説明が書かれたドキュメントを更新しなければ、ドキュメントは古くなります。古くなったドキュメントは今後のセッションでコンテキストとして読み込まれ、誤った説明に基づく誤ったコードを生成します。これは悪循環を生みます。古くなったドキュメントを信頼するセッションがあるたびに、状況はさらに悪化します。drift はアンカーを明示して強制することで、このフィードバックループを断ち切ります。

再リンクのゲート

drift link は、明示的なレビューなしに古くなったアンカーを再スタンプすることを拒否します。ターゲットのシグネチャが変化している場合、drift link は該当するドキュメントのセクションと、シンボルまたは Markdown 見出しのアンカーについては現在のターゲットのコンテキストを表示します。非 TTY の実行では終了コード 1 を返し、TTY の実行では確認を求めることができます。

つまり、何も確認せずに再リンクすることはできません。ドキュメントの文章を確認し、引き続き正確であることを確かめる必要があります。次を使用してください。

drift link docs/auth.md --doc-is-still-accurate

コードを変更した後

変更したターゲットを正確に参照しているドキュメントを探します。

drift refs src/auth/login.ts
drift refs src/auth/provider.ts#AuthConfig

または、すべてのドキュメントをまとめて確認します。

drift check

変更によってドキュメントが古くなった場合：

1. drift link <doc-path> を実行します。レビュー用のコンテキストが表示された後、処理が拒否されます
2. ドキュメントの該当セクションと、表示されたターゲットのコンテキストを読み、何が一致しなくなったのかを確認します
3. 変更内容を反映するようにドキュメントの文章を更新します
4. drift link <doc-path> --doc-is-still-accurate を実行します。レビュー済みであれば成功します
5. drift check を実行して確認します

この手順を省略しないでください。ドキュメントを古いままにすることは、ドキュメントを書かないことよりも悪い結果を招きます。

ドキュメントを変更した後

ドキュメント内のすべてのアンカーを更新し、現在の状態をスナップショットします。

drift link docs/my-doc.md

これにより、そのドキュメントに紐付けられた drift.lock 内の既存のすべてのバインディングの来歴が更新されます。現在の drift link <doc-path> の一括モードでは、ドキュメント本文からインラインの @./ 参照を検出したり追加したりしません。新しいターゲットは drift link <doc-path> <target> で明示的に追加してください。

新しいコードを作成したとき

新しいコードが既存のドキュメントで説明されている場合は、アンカーを追加します。

drift link docs/auth.md src/auth/new-handler.ts

新しいコードに専用のドキュメントが必要な場合は、ドキュメントを作成してリンクします。

drift link docs/new-feature.md src/feature/index.ts
drift link docs/new-feature.md src/feature/types.ts#Config

コードを削除または名前変更したとき

紐付けられたファイルが削除または名前変更されると、drift check は「file not found」とともに STALE として報告します。古くなったアンカーを削除します。

drift unlink docs/auth.md src/auth/old-handler.ts

ファイルの名前を変更した場合は、古いパスのリンクを解除し、新しいパスをリンクします。

drift unlink docs/auth.md src/auth/old-name.ts
drift link docs/auth.md src/auth/new-name.ts

名前変更を反映するようにドキュメントの文章を更新します。

リファクタリングしたとき

ファイル間でコードを移動したり、シンボルの名前を変更したりするリファクタリングでは、複数のドキュメントが一度に影響を受けることがあります。リファクタリング後に drift check を実行して、影響を受けたすべてのドキュメントを特定し、それぞれを更新します。

CI で drift check が失敗したとき

誰かがドキュメントを更新せずに、紐付けられたコードを変更しました。リンターの出力を読み、どのドキュメントがなぜ古くなったのかを確認して、ドキュメントの文章を更新した後、drift link を実行して来歴を更新します。

アンカーの構文

drift.lock のバインディング：

version = 1

[[bindings]]
doc = "docs/auth.md"
target = "src/auth/login.ts"
sig = "a1b2c3d4e5f6a7b8"

[[bindings]]
doc = "docs/auth.md"
target = "src/auth/provider.ts#AuthConfig"
sig = "c3d4e5f6a7b8a1b2"

[[bindings]]
doc = "docs/overview.md"
target = "docs/auth.md#authentication"
sig = "b3c4d5e6f7a8b9c0"

アンカーの対象には、コードファイル、コードシンボル（file#Symbol）、ドキュメントの見出し（doc.md#heading-slug）を指定できます。見出しのフラグメントには GitHub 形式のスラッグ（小文字、ハイフン）を使用します。

drift link は、コンテンツシグネチャ（sig = "<hex>"）とともにバインディングを drift.lock に書き込みます。コンテンツシグネチャは、対応言語では構文を考慮したフィンガープリント、非対応言語のファイル全体を対象とするアンカーでは生コンテンツのフィンガープリントです。非対応のシンボルアンカーはフィンガープリントを作成できません。古さの検出に VCS の履歴を照会する必要はないため、未コミットのファイルでも drift link を使用できます。先にコミットする必要はありません。

古くなったアンカーを再リンクする際、drift link は処理を拒否し、変更内容を確認できるようレビュー用のコンテキストを表示します。ドキュメントを更新する必要がないことを確認するには、--doc-is-still-accurate を渡します。

drift lint は、ロックファイルのルート以下で検出された Markdown ドキュメント内の Markdown リンク（[text](path.md)）についても、リンク先が存在するかを確認します。壊れたリンクは、ロックファイルのエントリーがなくても BROKEN として報告されます。

リポジトリをまたぐドキュメント（origin）

他のリポジトリからインストールされたドキュメント（このスキルなど）は、drift.lock 内のバインディングに origin を持ち、利用側のリポジトリで drift check がそれらのアンカーをスキップできるようになっています。他のリポジトリに配布するドキュメントを書く場合は、誤検出を防ぐために origin を追加します。

version = 1

[[bindings]]
doc = "docs/skill.md"
target = "src/main.ts"
origin = "github:your-org/your-repo"
sig = "a1b2c3d4e5f6a7b8"

古さ

drift check は drift.lock からバインディングを読み込み、アンカーが古いか、Markdown リンクが壊れている場合に終了コード 1 で終了します。影響を受けるドキュメントにチェック対象を絞り込むには、drift check --changed <path> を使用します。変更されたファイルが分かっている場合、CI で役立ちます。対応言語（TS/TSX/JS/JSX を含む TypeScript 系ファイル、Python、Rust、Go、Zig、Java）では、比較に構文を考慮するため、フォーマットのみの変更では古さは検出されません。変更されたアンカーについては、古いことを示すレポートに対象ファイルの Git コンテキスト（作成者、コミット、コミッターの日付、件名）が可能な範囲で含まれ、何が変更されたかを確認できます。

--format json の場合、ペイロードは schema_version: drift.check.v1 です（リポジトリの docs/check-json-schema.md を参照してください）。この場合、blame.date は作成者の日付ではなく、ISO 8601 の厳密な形式によるコミッターの日付です。リベース後に安定した時系列が必要な場合に使用してください。サマリーには、実際にチェックされたドキュメント数とスキップされたドキュメント数（例：origin の不一致）を示す verification_state（none | partial | full）が含まれます。

一般的な理由：

• ドキュメント作成後に変更 — ファイル／シンボルの内容が来歴スナップショットと異なります
• ファイルが見つからない — バインドされたファイルが存在しません
• ファイルを読み込めない — バインドされたファイルは存在しますが、読み込めません
• シンボルが見つからない — バインドされたシンボルがファイル内に存在しません
• フィンガープリントを取得できない — drift が対象のフィンガープリントを計算できませんでした
• ベースラインを取得できない — バインディングに使用可能な来歴情報がありません
• origin の不一致 — バインディングが別のリポジトリに属しているため、スキップされます
• リンク先が見つからない — Markdown リンクが存在しないファイルを指しています

drift lint は drift check のエイリアスです。