#ドキュメント

この記事を読んでまず引っかかったのは、速さや安さよりも「あとで辿れるか」をかなり真面目に測っているところだった。21ページを12分、$6.96で作れた、という数字はもちろん目を引く。でも読んでいて気になったのはそこではなくて、各ページが file:line で根拠を持ち、分からないことは「not stated in sources」と書くようにしている点だった。LLMで wiki を作る話は、うまくいけば便利、外すとそれっぽい嘘の山になる。その境目を、ここでは「ソースに戻れるか」で切っている。そこがいちばん実務的だと思った。 特にいいなと思ったのは、質問に対して LLM が平気で歴史を合わせに行かず、むしろ「あなたの前提が違う」と返しているところだ。timestamp の変更が 2.0 ではなく 1.0.0 にある、と修正していた話は象徴的で、こういう場面で黙ってユーザーの言い方に寄せないのは大事だと思う。ドキュメント生成で怖いのは、きれいにまとまることじゃなくて、きれいな嘘になることだから。そこを避けるために、LLM にも「分からないなら分からないと言え」と役割を与えているのが、この

GitHubのプロジェクトで、ドキュメントを wiki に置くべきか、それともリポジトリ内の `/docs` フォルダに置くべきか。この記事は、その定番の悩みにかなりはっきりした答えを出しています。筆者は wiki の利点を認めつつも、実際には欠点のほうが多く、GitHub の wiki はアンチパターンだとまで言い切ります。単なる好みの話ではなく、利用者と保守者の両方にとってどちらが扱いやすいか、という視点で整理しているのがポイントです。 元記事は、GitHub プロジェクトで「wiki を使うべきか、`/docs` フォルダを使うべきか」という議論が半年おきくらいに出てくる、と前置きしたうえで、自分の考えを明文化したものです。筆者は当初、「wiki でも `/docs` でもどちらも正しい選択肢」と書き始めたそうですが、書き進めるうちに見方が変わり、wiki を使う理由はほぼ一つしかないのに、使わない理由はたくさんあると結論づけています。そのため、GitHub の wiki はアンチパターンだと位置づけました。 筆者が認める wiki の利点は、リポジトリのどこからでも一クリックで

この記事を読んでまず思ったのは、AIエージェントそのものより、周辺の作法をどこまで先に決めておけるかで体験がかなり変わりそうだ、ということでした。Claude Codeみたいなツールは、単に「賢い補助輪」ではなく、チームのルールを食べて動く存在に近いのだと思います。 とくに引っかかったのは、AIにコードを書かせるときの不安が、もう「正しいかどうか」だけでは済まない点です。記事でも触れられていたように、`CLAUDE.md` や rule file、Auto Memory みたいな仕組みで、まず前提を揃える必要がある。これって結局、AIを入れるほどドキュメントの価値が上がる、ということでもあります。人間同士なら多少の暗黙知で回っていた現場が、AIを挟むと暗黙知のままでは回らない。そこは少し面倒だけど、逆に言えば、属人化した開発を見直すいいきっかけにもなりそうです。 もう一つ面白かったのは、AIに丸投げする話ではなく、PR作成やコード変更の入り口をどう設計するかに話が寄っていたところです。私はここにかなり現実味を感じました。AIがコードを全部「自動でよしなに」やってくれる未来より、変更範囲

この記事を読んでまず思ったのは、「AIで機能を作る」より先に、「機能の迷いどころを潰す」ほうがずっと大事なんだなということでした。 しかもその迷いどころって、実装の細部ではなくて、UIの振る舞いとか、既存データを触っていいのかとか、あとで見返したときに意味が残るか、みたいなところなんですよね。 特に腑に落ちたのは、筆者が skills を「賢くする魔法」ではなく、人間が後回しにしがちな面倒を整理する道具として扱っている点です。 `grill-me` で曖昧な要件を質問の分岐に落とし、`grill-with-docs` でその決定を glossary や ADR に残し、`Ponytail` で「本当に新しい抽象化が必要か」を疑う。ここ、かなり実戦的だと思いました。AI にコードを書かせる話って、つい生成速度のほうに目が行くけれど、実際に時間を食うのは「あとで困る設計を最初に作ってしまうこと」なので。 もうひとつ面白かったのは、デザイン系の skills を使う流れです。見た目を整える、ではなくて、同じアプリの中で UI の人格がブレないようにするために使っている

この記事を読んでまず思ったのは、これはかなり地味な見た目なのに、実際には相当いやな穴だということです。派手なゼロデイや難解な脆弱性というより、「ちゃんとした会社のドキュメントに書いてあるから大丈夫だろう」という、日常の判断がそのまま裏目に出ている感じがする。そこが一番ぞっとしました。 特に引っかかったのは、問題の中心が llms.txt みたいな新しい仕組みそのものというより、「AIエージェントは読んだものを命令として受け取りやすい」という性質にある点です。人間なら、`pip install` と書いてあっても「本当にそのパッケージ名で合ってるのか？」と少しは疑う。でもエージェントは、会社の公式ドメインにある、機械向けに整えられた文書を見たら、そこに書かれた手順をそのまま進めてしまう。しかも、周辺の監視ツールから見ると、ただの開発者が普通に package manager を叩いているようにしか見えない。守る側の目線では異常に見えにくいのに、攻撃の入口はもう開いている、というのが厄介です。 もうひとつ面白かったのは、これが「悪意ある文書が紛れ込んだ」話だけではないことです。もともと無害