DeepWikiのここがいい！
- 圧倒的ドキュメント量
- 引用元をこまめに掲示
- リポジトリに エージェントが生える
DeepWikiのここに注意！
- 圧倒的ドキュメント量
- 冗長な部分が多いかも...？
- ソースコードの実行確認はしていない
- 細かいハルシネーションはかなりある
- 由来となるドキュメントに注意
本記事は hooqアドベントカレンダー 9日目の記事です！
hooqは筆者作のOSSで、 ? 演算子にメソッドをフックしてくれるRust言語の属性マクロです。
hooqのためにチュートリアルドキュメントを執筆しました！もちろん私がです。この記事も私が書いてます。ちなみに私は人間です。
結構頑張ってこのチュートリアルを用意したのですが、その割には反応がなく虚しい...というわけで、魚の餌ぐらいにはなるかな1と思いhooqをDeepWikiに食わせてみました！
わざわざ詳細なチュートリアルを用意したOSSのDeepWikiを生成するとどうなるか？本記事ではDeepWikiと手書きドキュメントを比較してみて感じたことを軽くまとめたいと思います。
DeepWikiとは
Cognitionという会社が作ったソフトウェアエンジニアリングAI Devinの技術により、主にGitHubのパブリックリポジトリからドキュメントを生成してくれるサービスらしいです。
「AIがなんかいい感じにドキュメントを生成してくれる」以上のことは筆者もよくわかってないです！
ぶち込んでみる
deepwiki.com にアクセスすると、特に登録不要で一番左上のパネルでリポジトリを追加できるみたいでした！
hooqはパブリックリポジトリなのでそのURLを入力して送信 
Emailだけ入力必要でした。
しばらく待つとメールが来て、ドキュメントが生成されていました！
なかなか圧巻ですね 
URLは聞いていた通り頭の部分の https://github.com/ が https://deepwiki.com/ に変わっているだけです！
DeepWikiで感動・感心した点
DeepWiki製のドキュメントは、体裁としては非の打ちどころがありませんでした。本節で細かく見ていきます。
様々な視点で書かれた圧巻のドキュメント！
GitHubリポジトリ全体に関する情報については筆者すら把握していない視点・レベルで書かれている項目もあり、「え？何それ知らん...怖」と何度もなるレベルでした！
- 概要
- Getting Started
- リポジトリ構造
- コアコンセプト
- 開発
- ...
- FAQ
Overview記載のTesting and Quality Assuranceなどが良い例です。
The CI pipeline enforces:
- Zero compiler warnings via clippy -D warnings
- Code formatting with rustfmt (nightly)
- Dependency ordering with cargo-sort
- Full test suite execution across all workspace members
テストディレクトリの構成やCIの細かい説明なんてドキュメントに起こす気は毛頭なかったのですが、こういった細かい部分からしっかりと言語化してまとめてくれるため、こちらが ドキュメント化するのをサボっていた場所 に関しては代わりにやってくれているという感じで、新視点をたくさん与えてくれました。
引用元がこまめに掲示されている
Sources: hooq/docs/README.md 318-327 のように各説明のセクションの最後にリンクが記載されているのは好感が持てました。
後述のデメリットでハルシネーションが結構あるという話をするのですが、もしハルシネーションが起きている箇所でも、ソースとしているリンクから正しい知識を確認できるため、出展リンクが貼ってあるのは大切です。(つまるところハルシネーションは大体の場合は「書いてないことを推測して読む」場合に起きています。)
DeepWikiなりの表現・言葉・書き方で改められている
専門用語による説明部分にて、元のドキュメントと同一の単語・表現を使うのではなく、概念を理解した上でより分かりやすい単語・表現にしているであろう箇所が結構あり、しっかり読み込んだ上で出力を行っている感じがして好感でした。
例えばメタ変数の機能説明で、 Meta-variables provide compile-time and runtime context information that can be embedded in hook methods. という表現があり、「コンパイル時とランタイム時のコンテキスト情報」という表現があるのですがこういったアプローチでの説明は自分はしていません。
各機能・概念がどういったものであるかを踏まえて改めて言葉に書き起こしている感じであり、参照元のドキュメントをそのまま出力しているわけではない ということがわかります。グラフを多用して関係性をまとめるといったことをかなり頻繁に行っているのも関係していそうですね。
FAQがある
様々な視点で質問が作られていたのが良かったです！「こういう質問確かに来るかも...」と思えました。改善点として捉えるのも良いかも？
ただ少し残念だったのはこのページはハルシネーション多めでした...
DeepWiki付属のエージェント、Devinに質問してみた
Devinにコードベースについて聞ける機能があるみたいです！これはよさげですね！
FAQに記載がない内容をいくつか質問してみました！
Q. 「エラーの発生行をロギングしたい」という目的であればBacktraceで十分かと思います。それでもhooqを使うメリットはあるでしょうか？
A. Backtraceでもエラー発生行のロギングは可能ですが、hooqには以下のメリットがあります (以下、GitHubに筆者が示していた内容)
+αな回答を求めていたのですがそれは引き出せませんでした...ドキュメントに忠実そうではあります！
Q. hooqと同じようなことができる属性マクロクレートは他にありますか？
auto-context 等を期待していたのですが、外部検索してくれたりはしなさそうでした...あくまでも内部のドキュメントから回答するようです。
もう一つぐらい聞きたくて質問してみたのですが回答が返ってこなくなりました...無料だからでしょうかね？
ドキュメントから忠実に情報を取ってきてくれる一方、万能というわけではなさそうです。あくまでもプロジェクトの不明点を聞くなどの使い方がよさそうですね。
DeepWikiの良くないなと感じた点
多角的に情報をまとめてくれているのはありがたいのですが、頼りないなぁと感じた点も多々ありました！
ドキュメントが多すぎる！！！
長所にして欠点というわけです。 所有者の自分ですら全部のドキュメントに目を通せていないです 。英語だから読むのが大変というのも多少あるかもしれませんが、それ以上に情報の重複が多かったりそこまで重要ではない情報がフィーチャーされていたりして、読み切るのは至難の業でしょう。
結局読み手側が情報を適切に取捨選択する必要があり、後述するハルシネーションのこともあり信頼できるソースとするのは難しそうでした。
重複のわかりやすい例はOverviewページなどです。
こちらにRepository Structureという項があるのですが、別ページにもRepository Structure があります。 しかもそこに載っている図表は共通していないです。
重要度に関してはBasic Usageにも関わらず律儀にThe Transformation Processと題して裏でどのような動きをしているかをグラフに起こしている点などが冗長に感じました。丁寧なのは良いことですし特に間違えたりもしていませんが、読みやすいとは思えない感じですね。
簡潔に情報をまとめているという点では自分が書いたチュートリアルの方がまだ読みやすいんじゃないかなと思います。
細かいハルシネーションが多い
ぱっと見だと合っていてもよくよく見ると粗が目立ちます。以下見つけた誤りです(内容は読まなくて大丈夫です)。
-
Workspace Layoutの
hooq-helpersに関する説明で、flavor loadingとTOML parsingを含めると書いているのですがこれらの処理を行っているのはhooq-macrosクレートの方です -
Flavors,
hookフレーバーのMethod Templateが.hook($hook_meta)となっていますが実際は.hook(|| $hook_meta)です - Hook Target Detection Logic などにおいて、フック対象であるかの判別ロジックに若干誤りがあります
多くの図解で「 return_type_is_result が偽ならばフックしない」ことになっているのですが、 return_type_is_result が偽の場合でも tail_expr_idents に含まれる場合はフックされるのでこちらは誤りです。自分が用意したドキュメントは一応間違っていないはずですが、うまく説明できている箇所ではないため自分にも少なからず原因があるかも...
とにかく、 間違いだとわからないような間違い が結構含まれているので、なまじしっかりとドキュメントが整備されている分危ういかもしれません。
拾ってくるドキュメントの影響が大きい(のに、利用するドキュメントを指定できない)
前項で解説したハルシネーションを起こしている原因の一部なのですが、todo.mdというアイデアレベルの草稿を書きだしているファイルを参照して書かれた箇所がありました。
__base__ という表現はtodo.mdだけで出てくるもので実装には一切用いていません。
一つでも嘘につながってしまう情報があると、それを取り込んで掲載してしまうということがわかります。todo.md はほぼもう利用していないのにリポジトリに残していた自分が悪いのですが、取り込むファイルを調整できるようにしてほしいなと思ってしまいます。
逆に考えれば元となるドキュメントのうち訂正しなければならないポイントがわかるので、そういう意味ではメリットと言えるかもしれません。
ちなみにチュートリアルサイトの内容はあまり使われている感じがしませんでした...虚しい...
ソースコードの実行確認はされていない
いい感じにコード例を記載してくれますが、実行確認がされていないです。
以下はUsing with anyhowに記載の例です。
use hooq::hooq;
#[hooq(anyhow)]
fn parse_number(s: &str) -> anyhow::Result<i32> {
let num = s.parse::<i32>()?;
Ok(num)
}
#[hooq(anyhow)]
fn double_number(s: &str) -> anyhow::Result<i32> {
let num = parse_number(s)?;
Ok(num * 2)
}
#[hooq(anyhow)]
fn main() -> anyhow::Result<()> {
let result = double_number("not a number")?;
println!("{}", result);
Ok(())
}
DeepWiki曰く出力は以下のようになるそうです。
Error: [src/main.rs:12:18]
12> let result = double_number("not a number")?
|
Caused by:
0: [src/main.rs:7:15]
7> let num = parse_number(s)?
|
1: [src/main.rs:3:15]
3> let num = s.parse::<i32>()?
|
2: invalid digit found in string
しかし実際は let result = などの部分は出力されません！(自分の実装力不足のせいだったり...) 行番号も怪しいですね。
Error: [src/main.rs:17:47]
17> double_number("not ..mber")?
|
Caused by:
0: [src/main.rs:11:30]
11> parse_number(s)?
|
1: [src/main.rs:5:31]
5> s.parse::<i32>()?
|
2: invalid digit found in string
つまりプログラムの 出力はDeepWikiが予想したもの ということです2。「そりゃそうか」と筆者は納得しているのですが、Rustではない実行までに時間がかからない言語のリポジトリだったりすると実行確認はされていると思い込んでしまうのではないでしょうか...？
技術記事を執筆する際は必ずソースコードの実行確認を行う筆者的にはもやもやする部分です。
まとめ・比較結果
正直、手書きドキュメントを用意してよかった と思ってしまいました...下手なことが書いてあるドキュメントが存在すると、ありもしない事柄についての保証を求められたりしてしまいそうです。
一方で、DeepWikiのおかげで気づけた部分も色々ありました。
- 自身が作成したドキュメントに足りない情報は何か
- 自身のOSSのどういった部分が難しいか・AIでも勘違いしてしまうか
信頼できるソースにはなりにくいですが、たたき台としてはかなり良いものです。作成した意味はあったかなと思います。結局、ちゃんとやるなら筆者みたいに手書きとDeepWiki両方残すのがよさそうです！
最近はGoogleもCode Wiki というのを出したらしいのでこちらも別な機会に試してみたいですね。ここまで読んでいただきありがとうございました！