Coding Agent向けに、CLAUDE.md/AGENTS.md常時注入とdocs/adr参照、check-doc-freshness.shで鮮度監査する考察をまとめる
まず前提としてこれからドキュメントは人間が読まなくなる。書くのも読むのもAI。この前提からの議論が必要
コードさえあれば良い、ドキュメントは人間のためのもの、という人もいるが、コードは挙動、処理を表したものであり、目的やニーズを含まない。また、時代により陳腐化する。ドキュメントも腐るがコードも腐るのよ
specre をオススメしたい https://github.com/yoshiakist/specre/blob/main/README.ja.md
md+json-ldみたいなやつが来るんやろな
“とくにWhy notが記録されていないと、Agentが改善のつもりで過去に却下された設計に回帰するリスクがあります” なるほど
判断の文脈はすべてmdで残してあるのでこんど分類・整理させよう。あとシステムプロンプトの再構築。コンテクストドキュメント管理はセッション終了時の`/refine`でやらせる感じで行きたい。コード内コメントにポインタ
構造化された文章と自然文のどちらが生成AIにとって反映しやすいんだろうか？ちょっと調べてみる
Coding Agent時代のドキュメント まとまっている
全ての変更と作業ログを残している。でも一番効果があるのは複雑な処理やDBのリレーションを調べて保存したドキュメントかも。整理はめちゃくちゃ大変なのでノイズは妥協している。
私は AI と議論した結果の ADR を作成して（作成させて） docs/adr 以下に追加し、ずっと残しています
Architectural Decision Record (ADR) https://adr.github.io メモメモ
AIのためのドキュメントはDBとして削除や更新の運用を考えるべき。でゼロから組むならスキル化が良い。人間のドキュメントは都度そこから生成でいい。
.agentignoreが必要だ／ディレクトリ構造の概要をCLAUDE.mdに書いてもAgentのファイル発見速度は向上しなかったという結果が出ています
“Agentにとって扱いやすいのは、決定論的に検証可能か不変なドキュメント。コードから導出可能なものは書かず、検証可能な制約はテスト/Linterに移す方向で試している”
Coding Agent時代のドキュメントについて考えていること
Coding Agent向けに、CLAUDE.md/AGENTS.md常時注入とdocs/adr参照、check-doc-freshness.shで鮮度監査する考察をまとめる
まず前提としてこれからドキュメントは人間が読まなくなる。書くのも読むのもAI。この前提からの議論が必要
コードさえあれば良い、ドキュメントは人間のためのもの、という人もいるが、コードは挙動、処理を表したものであり、目的やニーズを含まない。また、時代により陳腐化する。ドキュメントも腐るがコードも腐るのよ
specre をオススメしたい https://github.com/yoshiakist/specre/blob/main/README.ja.md
md+json-ldみたいなやつが来るんやろな
“とくにWhy notが記録されていないと、Agentが改善のつもりで過去に却下された設計に回帰するリスクがあります” なるほど
判断の文脈はすべてmdで残してあるのでこんど分類・整理させよう。あとシステムプロンプトの再構築。コンテクストドキュメント管理はセッション終了時の`/refine`でやらせる感じで行きたい。コード内コメントにポインタ
構造化された文章と自然文のどちらが生成AIにとって反映しやすいんだろうか？ちょっと調べてみる
Coding Agent時代のドキュメント まとまっている
全ての変更と作業ログを残している。でも一番効果があるのは複雑な処理やDBのリレーションを調べて保存したドキュメントかも。整理はめちゃくちゃ大変なのでノイズは妥協している。
私は AI と議論した結果の ADR を作成して（作成させて） docs/adr 以下に追加し、ずっと残しています
Architectural Decision Record (ADR) https://adr.github.io メモメモ
AIのためのドキュメントはDBとして削除や更新の運用を考えるべき。でゼロから組むならスキル化が良い。人間のドキュメントは都度そこから生成でいい。
.agentignoreが必要だ／ディレクトリ構造の概要をCLAUDE.mdに書いてもAgentのファイル発見速度は向上しなかったという結果が出ています
“Agentにとって扱いやすいのは、決定論的に検証可能か不変なドキュメント。コードから導出可能なものは書かず、検証可能な制約はテスト/Linterに移す方向で試している”