CodeAlmanac: AI コーディングエージェント向けのライブコードベース Wiki

CodeAlmanac は、コードベースのライブ Wiki であり、アーキテクチャ上の決定、システム不変条件、複雑なワークフローなど、ソースコードだけでは伝えきれない高レベルのコンテキストを捉えます。Codex や Claude Code といった AI コーディングエージェントと統合することで、CodeAlmanac は開発者の会話から永続的な知識を自動的に抽出し、リポジトリ内にプレーンな Markdown ファイルとして保存します。これにより、人間も AI エージェントも一貫したバージョン管理された真実の情報源にアクセスできるようになります。

自動知識抽出とメンテナンス

CodeAlmanac は、コードベース Wiki を手動介入なしで最新の状態に保つためのバックグラウンドプロセス群を使用します。これらのプロセスはローカル macOS launchd ジョブとして実装されています。

• Sync: 5 時間ごとに、ツールは最近の Codex と Claude の会話をスキャンします。会話に登録済みリポジトリに関連する永続的な知識が含まれている場合、Wiki を更新するための ingest ジョブとしてキューに入れられます。
• Garden: 24 時間ごとに、ツールは Wiki をレビューし、古くなった情報や重複情報を削除し、リンクを改善し、全体的なナレッジグラフを洗練します。
• Update: 24 時間ごとに、ツールは CLI の更新をチェックし、インストールします。

コア機能とライフサイクルコマンド

CodeAlmanac は、Yoke SDK によって駆動される 3 つの主要ライフサイクルエージェント（build、ingest、garden）を通じて動作します。これらのエージェントは、almanac/ ディレクトリを編集するファイルシステム権限を持つ信頼できるローカルコーディングエージェントです。

知識のインジェスト

ingest コマンドは、外部素材を Wiki に取り込むことを可能にします。サポートされる入力は次のとおりです。

• ローカルファイルとディレクトリ
• Git diff とコミット範囲
• GitHub PR と issue
• URL とローカルエージェントのトランスクリプト

Wiki のガーデニング

garden コマンドは、ナレッジグラフの品質に焦点を当てます。古くなったページ、弱いリード、サポートされていない主張を特定・修正し、Wiki が高品質なリファレンスであり続けるようにします。

Wiki の閲覧

人間も AI エージェントも同じローカル読み取りコマンドセットを使用してコンテキストを取得します。

• codealmanac search: 特定のソースファイルへの言及や一致する Wiki ページを検索します。
• codealmanac show: ターミナルで特定の Wiki ページを開きます。
• codealmanac topics: 整理されたトピック一覧を表示します。
• codealmanac serve: 読み取り専用のローカル Web ビューアを起動し、Wiki をブラウズします。

技術アーキテクチャと統合

CodeAlmanac は Python (3.12+) で記述され、PyPI を通じて配布されます。プライバシーとセキュリティを確保するために、ローカル専用ツールとして設計されています。

リポジトリ構造

初期化時に、CodeAlmanac はリポジトリのルートに almanac/ ディレクトリを作成します。このディレクトリには以下が含まれます。

• README.md: Wiki のランディングページ。
• topics.yaml: ページをさまざまなフォルダに整理するために使用されるファイル。
• Markdown ファイル: architecture/、decisions/、guides/ などのフォルダに整理されます。

ランタイム状態と設定

リポジトリインデックスやグローバルデータベースなどの派生ローカル状態は ~/.codealmanac/ に保存されます。ユーザー設定は ~/.codealmanac/config.toml で管理され、auto_commit（エージェントが Git を介して Wiki の変更をコミットできるようにする）を切り替えたり、オートメーションジョブの頻度を設定したりできます。

コミュニティの視点と制限事項

ツールは AI が生成したコンテキストを体系的に捉える方法を提供しますが、一部のユーザーは AI 抽出知識の品質に懐疑的です。ある貢献者は、AI は具体的な実装詳細から高レベルの概念的飛躍へ抽象化するのが苦手で、強力な人間の指導がなければ Wiki の有用性が制限される可能性があると指摘しています。

現在の制約

• プラットフォームサポート: 背景自動化に launchd を使用しているため、現在は macOS のみサポートされています。
• プロバイダーサポート: 統合は Yoke SDK を介した Codex と Claude Code に限定されています。