agentic-para-kb という、Coding Agentが扱いやすいMarkdownナレッジベースのテンプレートを作りました。
リポジトリはこちらです。 https://github.com/nkoguchi-dev/agentic-para-kb

もともとのきっかけは、かなり厳しいセキュリティ要件に対応する業務が降ってきたことでした。
正直、自分だけで普通に進めていたら、とても間に合わない量と期間でした。
そこでCoding Agentをフル活用する前提で、要件、Word/Excelの資料、判断基準、作業状況、過去の決定をMarkdownに整理し、agentが毎回それを読んで作業できるようにしました。

これが思った以上にうまくいき、agentが単にコードを書くのではなく業務の前提情報を読んだうえで考えてくれるようになり、毎回ゼロから説明しなくても作業を進められるようになりました。

ただ、うまくいった仕組みも、自分の頭の中にあるだけでは再現できません。
試行錯誤して作ったナレッジベースの構想を自分でも正しく反映できるようにするため、個別の業務情報や個人情報を取り除き、フレームワークとして抜き出して言語化することにしました。
そうして作った汎用テンプレートが agentic-para-kb です。

何を作った？

テンプレートとして残した中身はそれほど大げさではありません。
PARAをベースにしたディレクトリ構造、agentが最初に読む AGENTS.md、各領域の入口になるMOC、未完タスクの集約、リンクチェック、アーカイブの扱いなどです。

特に意識したのは、「地図」と「本文」を分けることです。
AGENTS.md には常に読んでほしい薄い地図だけを置きます。
詳しいルールや判断基準は別の場所に置き、必要になったときだけ読ませます。
すべてを毎回読ませると重くなりますし、逆に地図がないとどこから読めばよいのか分かりません。このあたりの塩梅がかなり大事でした。

また、メール送信、デプロイ、公開状態の変更のような外向きの操作は人間が確認する前提にしました。
外部へ影響する操作は、agentが勝手に完了させないようにしています。
agentに任せる範囲を広げるほど、この境界をルールとして定義しないと大変なことになります。

なぜナレッジベースだった？

以前から、AIに渡す周辺情報の量と質で出力がかなり変わるとは感じていました。
名詞や単語がかなり怪しい文字起こしでも、固有名詞や背景情報を先に集めておくとその後の議事録や要約の精度がかなり上がります。
文脈が分かっているだけで、同じ音声やテキストからでも結果はかなり違います。

これは普段のChatGPTとの会話でも同じだと感じました。
こちらの事情や前提、よく使う判断基準を渡しておくと、返ってくる答えは明らかに良くなります。
逆に、毎回まっさらな状態から説明すると、同じような前提説明を何度も繰り返すことになります。

業務でCoding Agentを本格的に使うには、この前提情報を毎回チャットに貼るだけでは足りません。
要件や判断基準は増えていきますし、作業状況も変わります。
そこで、Markdownで正本を持ち、ソースコードをCodexに読ませるように読み込ませればよいのではないかと考えました。

ただし、Markdownを無作為に増やしていくと、すぐに破綻することも見えていました。
どれが今も有効な情報なのか、どれが古い記録なのか、現在のタスクはどこにあるのか、判断基準はどこにあるのか。
人間なら雰囲気で読めても、agentにとっては構造がない情報の山になります。

そこで、agentが読むことを前提にしたナレッジベースの構造が必要だと考えました。Markdownであれば何でもよい、というわけではなかったですね。

なぜPARAだった？

最初は、ソースコードのようにレイヤーで情報を管理できないかと考えていました。
普段扱っているコードでは、ドメインの中心と外側の実装を分ける設計に慣れています。
同じように、個人のメモや判断基準も構造で分けられると、agentに説明しやすくなるはずです。

そこで、ドキュメントやメモを構造化するためのフレームワークを探し、PARAを土台にすることにしました。
Projects、Areas、Resources、Archivesという分類は分かりやすく、特にProjectとAreaを分ける考え方が便利でした。
「いつ終わったと言えるか」があるものはProject、継続的に維持する責任はArea、という分け方はagentにも説明しやすいですね。

もう一つ気に入ったのが、ProjectやAreaを終えたあとに、再利用できる知識を蒸留してからArchiveするという考え方です。
終わったものをただ捨てるのではなく、今後も使えるルールや知識だけを残す。
これは、agentが古い情報を現在の根拠として拾ってしまう問題への対策にもなります。

ただ、PARAだけで十分だったわけではありません。
自分の用途では、構造ルールや判断基準のようにあまり動かしたくない情報を置く場所が必要でした。
そこで _core を追加しました。
また、いつ・なぜその選択をしたのかを残すために decisions も追加しました。
PARAをそのまま使うというより、agentが扱いやすいように少し拡張した形ですね。

追加して効いたもの

まず効いているのはMOCです。
各ProjectやAreaに入口となるMOCを置き、そこにステータスや次のアクションを集めるようにしました。
ファイルやディレクトリに番号を付けておくことで、agentが対象を見つけやすくなります。
人間向けの見栄えというより、agentが迷わず辿れることを優先しています。このあたりはかなり割り切りました。

次に、タスクの扱いです。
タスクは各ProjectやAreaのMOCに置き、それを横断ビューとして集約します。
これにより、作業開始時に未完タスクを一覧しつつ、詳しい文脈は元のMOCへ戻って確認できます。

会議メモの扱いも重要でした。
会議の文字起こしや議事録は、あくまで入力記録です。
その場で出たアクションや決定をすぐに各ProjectやAreaへ反映したくなりますが、議事録作成中のセッションでは反映先の文脈が薄いことがあります。
そこで、複数領域にまたがる決定が出た場合は、まず「関連するProjectやAreaを読んだうえで反映する」というTODOを作るようにしました。
これにより、文脈の浅い状態で間違ったタスクを作る事故を減らせます。地味ですがかなり効いています。

さらに、メッセージやメールなどの情報も必要に応じて読み込めるようにすると、返信文や議事録のドラフト精度がかなり上がります。
agentは文章を書くのが得意ですが、周辺情報がないと一般論になりがちです。
逆に、文脈が揃っていると、かなり実用的な下書きを作れるようになります。

運用を始めてみて

運用を始めてみると、狙いはかなり合っていたと感じています。
毎回ゼロから説明しなくても、agentがMOCや関連メモを読んで作業を始められるようになりました。
開発タスクの作成、メール返信、議事録作成のような作業では、周辺情報が蓄積されている効果が分かりやすく出ます。

一番効果が大きかったのは、業務での開発タスク作成です。
ドメインオーナーとの打ち合わせ内容、そこで決まったこと、機能を作る背景、既存コードの状態をagentがまとめて読んだうえで、「なぜこの変更を行うのか」を理解してくれます。
そのうえで、コードの変更が必要な箇所を把握し、JiraのチケットをMCP経由で作成できるようになりました。
単に議事録からTODOを抜き出すのではなく、背景とコードの両方を見たうえでタスクに落とせるのが大きいですね。

もう一つ大きいのは、メールのドラフト作成です。
大手企業の担当者にメールする場合でも、社内での決定、利用者向けの確認結果やアンケートの結果、アプリケーションの現在の状態などを踏まえて下書きを作ってくれます。
そのため、以前より手直しがかなり少なくなりました。
文章を書く能力だけでなく、前提情報を正しく持っていることが効いているのだと思います。

一方で、問題もあります。
情報量が増えるほど重くなります。
読むファイルが多ければ遅くなりますし、Tokenの利用量も増えます。
何でも読ませればよいという話ではなく、どこまでを常時読む地図にして、どこからを必要なときだけ読む本文にするかは、まだ調整が必要です。このあたりは少し悩ましいですね。

その意味では、agentic-para-kb は完成品というより、agent時代の知識管理を試すための最初の型です。
Markdownで情報を持つだけなら簡単ですが、agentが扱える形で育てていくには、構造と運用ルールが要ります。
しばらく使いながら、ちょうどよい重さと粒度を探していきたいと考えています。