1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

OpenWikiを動かしたら、CLAUDE.mdとAGENTS.mdまで書き換えられた

1
Posted at

はじめに

CLAUDE.md や AGENTS.md にプロジェクトの前提を書いておくと、コーディングエージェントの精度は上がる。ただし、これらのファイルはコードが変わっても自動では更新されない。PRを重ねるたびに「あの説明、もう古いのでは」という不安が積み上がっていく。

LangChainが2026年7月にリリースしたOpenWikiは、この前提を検証できるツールだった。「コードのdiffを見てドキュメントを追従させるエージェント」を謳っており、実際にサンプルリポジトリへ --init と --update を通してみたところ、CLAUDE.md と AGENTS.md を無断ではなく明示的な設計として書き換える挙動が確認できた。

本記事では実際に動かしたログを元に、OpenWikiが何を生成し、生成物とエージェント指示ファイルをどう関連付けるのかを見ていく。

TL;DR

  • OpenWikiは openwiki/ 配下に構造化ドキュメントを生成し、CLAUDE.md と AGENTS.md には その入口だけを指す短いブロック を追記する（ドキュメント全文を指示ファイルに埋め込まない設計）
  • --update はgit diffを読み取り、変更された関数だけをピンポイントで書き直す。手動で書いたテストリポジトリでの実行では、追加した関数の副作用まで正しく言い当てた
  • 生成されるGitHub Actionsワークフローは、--init 時に使ったモデルプロバイダとは無関係に既定でOpenRouterを使う設定になっており、そのままでは動かない
  • 実行中に「/openwiki/ 配下以外への書き込みは拒否する」というサンドボックス制約のログが実際に出た。書き込み範囲を絞る設計が動作レベルで機能している

OpenWikiとは

OpenWikiはLangChainが公開したCLIで、openwiki パッケージとして配布されている。公式ブログによれば、DeepAgentsフレームワーク上に構築されており、OpenAI・Anthropic・OpenRouter・Fireworks・Basetenなど複数のモデルプロバイダに対応する。GitHubのリポジトリは2026年7月21日時点で12.7k star・MITライセンス（TypeScript 87.7%）で、npmパッケージは2026-06-26の 0.0.0 から2026-07-20の 0.2.1 まで、約1か月で10回のリリースを重ねている。

公式ブログが明言している設計思想は「ドキュメント全文を CLAUDE.md のようなエージェント指示ファイルに埋め込むのは無駄が多く保守しづらい」という点だ。かわりに CLAUDE.md/AGENTS.md には短い参照ブロックだけを置き、詳細は openwiki/ 配下の個別ファイルに分離する。この分離自体は珍しい発想ではないが、実際にそれがどう書き込まれるのかは動かしてみないと分からない。

実際にセットアップして動かした

検証用に、greet 関数だけを持つ最小のNode.js CLIリポジトリを作成し、Claude Codeのクラウド実行環境で npm i openwiki@0.2.1 をインストールした。モデルプロバイダは環境変数の OPENAI_API_KEY を使い、CLIが自動的にOpenAIプロバイダ（gpt-5.6-terra）を検出した。

╭──────────────────────────────────────────────────────────────────────────────╮
│ >_ OpenWiki v0.2.1 agent docs for codebases                                  │
│ provider: OpenAI                                                             │
│ model: gpt-5.6-terra                                                         │
╰──────────────────────────────────────────────────────────────────────────────╯

openwiki --init -p（一度実行して結果を表示するprintモード）を実行すると、以下のファイルが生成された。

AGENTS.md
CLAUDE.md
openwiki/.last-update.json
openwiki/cli-behavior.md
openwiki/index.md
openwiki/maintenance.md
openwiki/quickstart.md
.github/workflows/openwiki-update.yml

quickstart.md にはCLIの起動コマンドと期待される標準出力、cli-behavior.md には引数の扱いや greetings.log への追記が同期的（fs.appendFileSync）である点まで、ソースを正しく読み取った説明が書かれていた。ここまでは「コードを読んでドキュメントを書く」という謳い文句どおりの動作だ。

AGENTS.mdとCLAUDE.mdへの書き込み内容

今回の検証で最も具体的に確認できたのは、指示ファイルへの書き込み内容そのものだった。CLAUDE.md と AGENTS.md はどちらも同一のマーカー付きブロックが追記されており、中身は次の4行だけだった。

<!-- OPENWIKI:START -->

## OpenWiki

This repository uses OpenWiki for recurring code documentation. Start with `openwiki/quickstart.md`, then follow its links to architecture, workflows, domain concepts, operations, integrations, testing guidance, and source maps.

The scheduled OpenWiki GitHub Actions workflow refreshes the repository wiki. Do not hand-edit generated OpenWiki pages unless explicitly asked; prefer updating source code/docs and letting OpenWiki regenerate.

<!-- OPENWIKI:END -->

OPENWIKI:START/END のマーカーで囲われているため、次回の --update 実行時にはこのブロックだけを差し替え、指示ファイルの他の記述には触れない仕組みになっている。公式ブログが説明していた「短い参照だけを置く」という方針は、実際のファイル差分としてそのとおりに現れていた。

コードを変更して --update を試す

次に、greet 関数を持つ元のソースへ farewell 関数を追加し、module.exports でエクスポートするよう変更してコミットした。そのうえで openwiki --update -p を実行し、差分だけを正しく反映できるかを確認した。

更新後の cli-behavior.md には次の記述が追加されていた。

src/index.js はCommonJSで { greet, farewell } をエクスポートする。モジュールを require すると先に main() が実行されるため、挨拶コマンドは process.argv を読み取り、greetings.log へ書き込み、標準出力へ出力する処理を引き続き行う。exports が使えるようになるのはそのあとである。

このモジュールは末尾で main() を無条件に呼んでいるため、require するだけで副作用（ログ書き込みと標準出力）が実行される。ソースコードの実行順序まで踏まえた説明であり、diffの表面的な差分だけでなく実行時の挙動を推測した記述になっている点は、単純なdiff要約ツールとの違いだった。

GitHub Actions連携の中身を覗く

--init が生成した .github/workflows/openwiki-update.yml は、毎日UTC 8時（JST 17時）に openwiki code --update --print を実行し、変更があればPRを作成する内容だった。ここで実際のYAMLを確認すると、モデルプロバイダの指定が次のようになっていた。

- name: Run OpenWiki
  run: openwiki code --update --print
  env:
    OPENWIKI_PROVIDER: openrouter
    OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
    OPENWIKI_MODEL_ID: z-ai/glm-5.2

今回の --init はOpenAIプロバイダで実行したにもかかわらず、生成されたワークフローは既定でOpenRouter経由のGLM-5.2を指定していた。つまりこのワークフローは、リポジトリのSecretsに OPENROUTER_API_KEY を追加しない限りそのままでは失敗する。--init で使ったプロバイダの認証情報を引き継いでくれるわけではなく、スケジュール実行を有効にするなら生成後にワークフローのenvブロックを手直しする必要がある。

実行中に見えたガードレール

--update 実行中には、想定していなかった次のログも出力された。

Failed to offload conversation history to /conversation_history/session_xxx.md:
OpenWiki repository init/update runs may only write under /openwiki/. Refused path: /conversation_history/session_xxx.md

会話履歴をリポジトリ外のパスへオフロードしようとした処理がガードレールに拒否され、続けて要約処理にフォールバックしていた。エラーメッセージが明示するとおり、init/update 実行時の書き込み先は openwiki/ 配下（および CLAUDE.md/AGENTS.md/ワークフローファイルの追記）に制限されており、それ以外のパスへの書き込みは実行時に拒否される。ドキュメント生成ツールが任意のパスに書き込める設計だと事故のもとになるため、この制限は動作として確認できる形で効いていた。

著者視点の発見ポイント

本プロジェクトは CLAUDE.md と docs/rules/*.md をHot層・Warm層に分けて管理しており、全ルールを1ファイルに詰め込むとコンテキストを圧迫するという課題に日常的に向き合っている。OpenWikiが採用していた「指示ファイルには入口だけを残し、詳細は別ファイルへ逃がす」設計は、この課題への一つの解法として同じ方向を向いている。差分は、本プロジェクトが人間の判断でHot/Warm層を割り振っているのに対し、OpenWikiはコードのdiffを見て機械的にその境界を維持しようとする点だ。ドキュメントの陳腐化をコミットのたびに人力で気づくのではなく、スケジュール実行に持たせるという発想自体は、自前のルール管理にも応用できそうだと感じた。

まとめ

OpenWikiは「コードのdiffを見てドキュメントを追従させる」という謳い文句どおりに、コミット単位でのピンポイント更新と、指示ファイルへの最小限の参照ブロック追記を実際にこなした。一方でスケジュール実行用のワークフローは初期化時のプロバイダ設定を引き継がないため、CI導入時には認証情報の設定し直しが要る。導入する際は、生成された .github/workflows/openwiki-update.yml のenvブロックを一度は目視で確認したほうがいい。

参考リンク

1
0
2

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?