📚

Linear Loopsに「古くなったドキュメント」を見つけてもらう仕組みを作った🔁

に公開

はじめに

AIによる実装が当たり前になってくると、コードが変わるスピードも上がっていきます。

私たちのチームでも、Claude Codeを中心にAIを活用した開発が進んでいます。
その一方で、コードの変化にドキュメントが追いつかないことが気になるようになってきました。

そこで今回、Linearの新機能である Loops を使って、Linear上のドキュメントが実装やチームの実態とずれていないかを毎月チェックしてもらう仕組みを、ラッコキーワードの開発チームで作ってみました。

対象読者

  • Linearのドキュメント機能に、手順書や仕様メモを置いているチーム
  • Linear Loopsを試してみたいけれど、どんな用途に使えるかイメージが湧いていない人

背景・課題 🤔

ラッコキーワードの開発チームでは、ドキュメントを「誰が読むか」で置き場所を分けています。

置き場所 主な読み手 例
リポジトリ(docs/) エンジニア(とAIエージェント) コーディング規約、設計ガイドライン、DB・ESなどの定義書
Linearのドキュメント エンジニア以外も含むチーム全体 運用手順書、料金表、オンボーディングガイド

基本的にエンジニアしか見ないドキュメントはリポジトリで管理しています。
コードと同じPRで更新でき、Claude Codeなどのエージェントもそのまま参照できるからです。

一方、Linearのドキュメントはコードの変更と同じPRでは更新されません。
実装が変わっても、誰かが思い出して直さない限り古いまま残ってしまいます。

ドキュメントは書いた瞬間から古くなり始めますが、Linear側は特にその傾向が強くなります。

  • 実装で定数や環境変数名が変わったのに、手順書が古いまま
  • メンバーが入れ替わったのに、オンボーディングガイドの「チーム体制」が古いまま

気づいた人が直すのが理想ですが、実際には「誰も気づかない」か「気づいても後回し」になりがちです。

AIで実装のスピードが上がるほど、このずれは広がりやすくなります。そこで、定期的に機械的にチェックして、人に気づかせる仕組みを作ることにしました。

やったこと 💡

Linear Loopsとは

Loopsは、Linear Agentに書いた指示を、スケジュールやイベントをきっかけに自動で実行させる機能です(公式ドキュメント)。

  • トリガー:定期実行(毎時〜毎年)か、issue / project / initiative / cycle / release の変更
  • 指示:自然文で書く
  • 権限:操作できるチーム、Web検索、リポジトリの読み書き、SlackやMCPコネクタなどをループごとに設定する
  • 費用:AIクレジットを消費する。公式ドキュメントでは、コーディングセッションを伴わない実行は1回あたり$0.07〜0.20が目安とされている

公式ドキュメントでも、Linear社内の活用例として「ヘルプドキュメントが古くなったらループが修正案を出す」が挙げられていて、今回やりたいこととほぼ同じでした。

ループの全体像

ループにはドキュメント本文を編集させず、食い違いを見つけたらコメントで指摘するだけにしています。直すかどうかは人が判断します。

ループの設定

項目 値
作成場所 チームの Loops タブ(チーム単位のループ)
トリガー 毎月1回(Asia/Tokyo)
Team access 対象チームのみ
Reasoning level Auto
Web search OFF
Access code Read
Allow changes to externally synced issues and comments OFF
Connectors Slack

実行頻度は、最初は毎週で設計していましたが、最終的に月1回にしました。

Access code は、公式ドキュメントで「Code Intelligence」と書かれている権限に当たるようです。Read にしておけば、リポジトリは読めますが、PRを作る権限は持ちません。

指示文

実際に使っている指示文です(メンバー名やチャンネル名は置き換えています)。

チーム直下のドキュメント(プロジェクト・issueに紐づかないもの)を対象に、記載内容が現在のリポジトリの実装・チームの実態と食い違っていないか確認する。

確認観点:
1. コード上の名前:関数、API、環境変数、テーブル/カラム、ESインデックス、バッチ名が今も存在するか
2. 設定値:料金、クレジット消費量、プラン制限、タイムアウトなどが実装の値と一致するか
3. 手順:コマンド、npm script、ファイルパス、画面名が今も有効か
4. チーム体制:記載メンバーが実際の稼働状況と合っているか
   - 直近90日に、チームの issue で担当またはコメントをした人、リポジトリでコミットまたはPRを作成した人を「稼働メンバー」とみなす
   - 記載されているのに稼働が見られない人、稼働しているのに記載がない人を、根拠(issue ID / PR番号を最大3件)付きで挙げる
   - 役割(開発 / UI/UX / インフラ など)は「推定」と明記する
   - 外部チームのメンバーは削除候補にせず「要確認」とする

指摘の残し方:
- 該当箇所にインラインコメントを残す。内容は「何が古いか」「根拠(ファイルパスと該当箇所、または issue ID / PR番号)」「修正案」の3点
- 確信が持てないものは「要確認」と明記する
- 同じ指摘の未解決コメントがすでにある場合は新しく付けない
- 食い違いが無いドキュメントにはコメントしない

レビュアー割り当て:
- 候補者: @Aさん, @Bさん, @Cさん, @Dさん(この順で番号0〜3)
- 実行月の月番号(1〜12)を M、指摘のあったドキュメントを名前順に並べた番号を i(0始まり)とし、(M + i) を候補者数で割った余りの番号の人をレビュアーにする
- 選ばれた人がそのドキュメントの最終更新者だった場合は、次の番号の人にする
- そのドキュメントの指摘コメントの冒頭でレビュアーをメンションする

実行後の報告:
- 実行の最後に Slack の #(テスト用チャンネル) へ結果を投稿する
- 投稿内容は、指摘のあったドキュメントごとに「ドキュメント名(リンク)/レビュアー名/コメント件数/指摘の要約1行」
- 指摘が0件の場合は「指摘なし(確認したドキュメント数: N件)」とだけ投稿する
- Slack の投稿ではメンションしない。@here や @channel も使わない

禁止事項:
- ドキュメント本文を直接編集しない
- issueの作成・ステータス変更・担当者変更をしない

結果:やってみて分かったこと 📊

最終更新日は「古さ」の指標にならなかった

最初は「最終更新から180日以上経ったドキュメントを一覧にする」という観点も入れるつもりでした。

ところが実際にドキュメントの一覧を取ってみると、チーム直下の11件のうち8件の最終更新日が同じ日に集中していました。別ツールからLinearへ移行した日だと思われます。

これでは更新日で古さは判断できないので、中身を実装と突き合わせる観点だけに絞りました。

チームの所属メンバーと「実際に関わっている人」は一致しない

オンボーディングガイドの「チーム体制」を最新に保ちたい、というのも動機の一つでした。

最初はLinearのチームメンバーと照合すればいいと考えていましたが、照合してみると次のようなずれがありました。

  • チームに所属しているけれど、ほとんど関わっていない人がいる
  • インフラ担当や他部署の人は、別チームで活動していて所属していない

所属だけで判断すると誤った提案が増えてしまうので、直近90日のissue活動とコミット・PRで「稼働メンバー」を定義しました。さらに、他部署のメンバーはLinear上の活動が少なくても在籍している可能性が高いため、削除候補ではなく「要確認」にしています。

最初の実行では、どこにコメントが付いたのか分からなかった

試しに実行してみたところ、どのドキュメントのどこにコメントが付いたのかが分かりませんでした。

ループのRun historyを開けば実行内容は確認できますが、毎回そこまで見に行くのは現実的ではありません。そこで、実行の最後にSlackへ「どのドキュメントに何件指摘したか」を投稿してもらうようにしました。

ただし、ループが投稿できるのは公開チャンネルだけです。通知用の非公開チャンネルは使えなかったので、最初はテスト用の公開チャンネルに投稿させています。

レビュアーへの依頼は、Slackよりドキュメントのコメントが向いていた

ドキュメントごとにレビュアーを決めるにあたり、「コメントでメンション」と「Slackでメンション」を比べてみました。

コメントでメンション Slackでメンション
依頼先の正確さ 指摘箇所そのものに紐づく 本文からリンクを辿る必要がある
対応状況の管理 コメントをresolveすれば完了が分かる 対応済みかどうかが追えない
返信 コメントスレッドで議論できる ループからのDMは一方通行

コメントでメンションすれば、対応するかどうかの議論と完了の記録が指摘箇所にまとまります。Slackは「今回の結果一覧」に役割を絞り、メンションはしないことにしました。両方でメンションすると、同じ通知が二重に届いてしまうためです。

「ランダムに選んで」はAIに任せない方がいい

レビュアーは固定せず、毎回変えたいと考えました。

ただ、指示文に「ランダムに選んで」と書くだけだと、AIの選び方が偏って同じ人に依頼が続く可能性があります。そこで、実行月とドキュメントの並び順から計算する輪番にしました。

月ごとに割り当てがずれるので担当が固定されず、計算で決まるので「なぜこの人なのか」も説明できます。最終更新者を外すルールも加えて、自分で書いた内容を自分でレビューしないようにしています。

次は「運用結果を見ながらの調整」を試したい 🔍

まだ動かし始めたばかりなので、しばらく運用しながら次のことを見ていく予定です。

  • 誤検知が多い確認観点はないか
  • インフラ手順書など、リポジトリだけでは確認しきれないドキュメントを対象に残すべきか
  • 指摘がどのくらいの割合で実際の修正につながるか
  • 安定したら、Slackの投稿先をテスト用チャンネルから通知用チャンネルに移す

まとめ 📝

Linear Loopsでドキュメントの陳腐化チェックを作ってみて、次のようなことが分かりました。

  • 👉 「古さ」は更新日ではなく中身で判断する。 移行などで、更新日がまとめて揃っていることがある。
  • 👉 「チーム体制」は所属ではなく活動で判断する。 所属しているだけの人も、別チームで活動している人もいる。
  • 👉 出力は「どこに何を指摘したか」が人に分かる形にする。 Slackへのまとめ投稿が有効だった。
  • 👉 依頼はドキュメントのコメントで、Slackは一覧だけ。 対応の議論と完了の記録が指摘箇所にまとまる。
  • 👉 「ランダム」はAIに任せず、計算で決めさせる。 偏りがなく、割り当ての理由も説明できる。
  • 👉 まずは「指摘だけ」から始める。 料金表や手順書など、誤りの影響が大きいドキュメントもある。

おわりに ✨

AIを活用した開発が進むほど、コードは速く変わっていきます。
エンジニア向けのドキュメントはコードと一緒にリポジトリで更新できますが、チーム全体で読むLinearのドキュメントは、どうしても取り残されがちです。

Loopsは指示文と権限の設定だけで始められるので、「古くなっていそうだけど、見直す時間が取れない」ドキュメントがあるチームは、まずは指摘だけさせる形で試してみるのがおすすめです。

私たちも月1回の運用を続けながら、確認観点や対象のドキュメントを調整していく予定です🙌

弊社では、AIを活用した開発だけでなく、こうした開発プロセスの改善にも一緒に取り組んでくれる仲間を募集しています。興味があればぜひのぞいてみてください。

参考

ラッコ株式会社

Discussion