Posts on 耳順

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

最高気温のヒートマップ

Mon, 23 Feb 2026 00:00:00 +0900

気象庁が観測している気温データをヒートマップで表示するだけのアプリを作ってみました。
https://heat-chronicle.koppepan.org

リポジトリはこちらです。 https://github.com/nkoguchi-dev/heat-chronicle
せっかくAWSで公開するところまできちんとやったのでメモを残しておきます。

なぜ作った？

過去に何かのニュースで過去100年のデータをヒートマップで表したという画像を見た記憶があり、自分の住んでいるところのデータも見てみたいと考えたのがきっかけでした。要するに模倣ですね。

また昨今のAIコーディングが非常に優れているために「有名サービスの自分専用カスタマイズ」のようなアプリケーションを作成して自分だけが楽しんで利用する、ということができるようになりました。Claude Coworkの発表が引き金となってIT企業の株価が暴落した、といったニュースが流れていたので実力を試してみたくなったというのが動機です。

どうやって作った？

作り方は現在では一般的と思われる方法で、Claude Coworkを使って仕様を詰めてClaude Codeで実装する形です。Coworkはまだ制限が多くファイルの削除ができないなどコーディングするには向いていない制約があったのでコード全体を把握したCoworkと一緒に設計を考えながら設計書を出力、Claude Codeで実装をする形にしました。感覚としては以前あったClaude Codeのプランモードでプラン部分だけOpusを使う形に近いです。

実装は全てお任せで自分では1行もコードを書いておらず、コードのチェックもコミット前におかしな箇所がないか軽く確認した程度です。そのためコード全体をきちんと確認すると改善すべき箇所は多くあると思いますが、自分で決めた大まかなコーディング規約が守られていれば細かい点は気にしなくてもよいのではないかと考えています。

実装から公開までにかかった時間はデータを表示するまで3時間程度、そこからAWSで動作できるまで1日、諸々の調整に半日ほどでした。AWSのリソース作成はTerraformで行ったため、こちらもClaude Cowork/Codeを利用して作っています。

振り返りと今後に向けて

技術選定

フロントエンド: Next.js（SPA）
バックエンド: Python + FastAPI
データベース: DynamoDB
AWSで動作させるためのランニングコストを限りなく低く抑えるためにLambda + DynamoDBで動作させるようにしています。
DynamoDBは初めてだったので少し学習する必要がありました。ほんの少しだけですが。

最初の設計と実際のズレ

ローカルでしか動かすつもりはなかったので細かいことは考えていなかったのですが、3時間程度とあまりに早くアプリケーションが動いてしまったので欲が出てAWSで稼働させるためにデータベースをDynamoDBに変更しています。
最初からDynamoDBを想定していればもっと早く作れたかもしれません。早すぎて恐ろしいですね。

上手くいった点

Claude Coworkができること／できないことを把握することができました。プログラムだけならClaude Codeだけで良いのでは？と考えていましたが、仕様を練る部分ではOpus4.6を利用したCoworkが相手の方が良いようです。Claude Codeとできることに差がなさそうですが何か違いがあるのでしょうか？
またEC2やECSではなくLambdaでバックエンドを動作させるという経験ができたのが大きいですね。
Pythonだと遅いのではないか、Rustで作る必要があるのではないかと考えながら実装を進めましたが動かしてみるとPythonでもあまり気にならない速度でした。コールドスタートは気持ち待たされますがこの程度なら許容範囲内ですね。目新しさや使ってみたい感からRustが選択肢に上がってしまうことが多いのですが、大半はPythonで何とかなる＋何も問題がないという事も分かっているのでPythonで済ませることができたのは良かった点だと考えています。

次は改善したい点

DynamoDBは名前くらいしか知らない状態で把握できていなかったので、概要と簡単な利用方法くらいは把握しておけば良かったかなと少し後悔がありました。
その他は技術選定・実装期間・ランニングコストと及第点だったと考えています。

構成

フロントエンド: Next.js 16 / React 19 / TypeScript / Tailwind CSS v4
バックエンド: Python 3.12 / FastAPI
データベース: Amazon DynamoDB（ローカル開発は DynamoDB Local）
インフラ: AWS Lambda + API Gateway / S3 + CloudFront / Terraform
CI/CD: GitHub Actions / AWS ECR