agentic-para-kbを作った

Wed, 08 Jul 2026 00:00:00 +0900

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を作るようにしました。
これにより、文脈の浅い状態で間違ったタスクを作る事故を減らせます。地味ですがかなり効いています。

Ai on 耳順

agentic-para-kbを作った

何を作った？

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

なぜPARAだった？

追加して効いたもの