CodeAlmanacとは？AIコーディングを強化するコードベースWikiの導入手順

同じ落とし穴に、AIが何度もはまる。先週わざわざ説明した「このテーブルは直接触らない」という約束を、新しいセッションのAIは平気で破ってくる。原因ははっきりしています。あなたのチームが持っている判断の履歴が、コードのどこにも書かれていないからです。

CodeAlmanacは、その抜けた部分だけを埋めにいくツールです。

---

CodeAlmanacとは、AIエージェントに「コードに書けない事情」を渡す仕組みです

CodeAlmanacとは、リポジトリの中にmarkdownのwikiを作り、AIコーディングエージェントがそれを読み書きしながら育てていくオープンソースのCLIツールです。公式リポジトリは、AIに渡すべき情報を「なぜこの形になっているのか」「以前なにが壊れたのか」「どの前提を崩してはいけないのか」「処理がどのファイルやサービスをまたぐのか」の4つで説明しています。

ソースコードを全部読ませれば分かる、という話ではありません。コードが語れるのは「今どうなっているか」だけ。決定の理由や過去の事故は、コードから消えています。

wikiの実体はプレーンなmarkdownで、リポジトリの almanac/ 配下に置かれます。検索用の索引はローカルで作られ、変更はGitのdiffとして普通にレビューできます。開発元のAlmanacCodeはY Combinator S26に採択されており、ライセンスはApache-2.0です。

特徴を先に整理しておきます。判断材料はこの表がいちばん早いはずです。

つまり、「AIの記憶をSaaSに預ける」タイプではなく、記憶をリポジトリの一部として自分の手元に持つタイプです。

---

なぜAIエージェントは、コードを全部読ませても間違えるのか？

理由は3つに分けられます。ここを理解しないと、wikiに何を書くべきかがぶれます。

1つ目は、意図が残らないこと。retry = 3 と書いてあっても、なぜ5でも1でもなく3なのかは誰も知りません。当時の障害対応で決まった数字なら、それはコードの外にあります。

2つ目は、失敗の履歴が消えること。一度事故を起こして直した箇所ほど、直った後のコードは何事もなかった顔をしています。AIは平気で元の書き方に戻します。

3つ目は、処理がファイルをまたぐこと。決済フローが5ファイル3サービスにまたがっていると、AIは自分が開いた1ファイルの中だけで筋の通った変更を書き、全体としては壊します。

AIが賢くなっても消えない穴です。文脈の欠落は能力の問題ではなく、情報がそもそも存在しない問題だからです。

CodeAlmanacはこの3つを、それぞれ「決定（decisions）」「壊れた履歴と守るべき前提」「ファイルをまたぐ流れ」として書き留めることを狙っています。

AIコーディング環境そのものの選び方から整理したい場合は、AIコーディングツールの一覧を先に眺めておくと、この記事の後半が読みやすくなります。

---

almanac/ には何が作られるのか

codealmanac init を実行すると、リポジトリ直下に almanac/ が作られます。公式ドキュメントが示す初期構造は次の形です。

your-repo/
|-- almanac/
|   |-- README.md
|   |-- topics.yaml
|   |-- architecture/
|   |   |-- README.md
|   |   `-- indexer.md
|   |-- decisions/
|   |   `-- local-first.md
|   `-- guides/
|       `-- setup.md
|-- src/
`-- ...

folderの意味を並べると、書くべき中身が見えてきます。

つまり、社内wikiとしても普通に読める形のまま、AIの参照元になります。人間用とAI用を二重管理しなくて済むのが効いてきます。

なお、almanac/topics.yaml と almanac/README.md の両方が存在するリポジトリを、CodeAlmanacは自動的に「wiki登録済み」と判定します。この2ファイルが目印。手で消すと認識から外れます。

---

導入手順1: インストールと初期設定

前提条件を先に確認してください。対応OSはmacOSのみで、Python 3.12以上、そしてCodexかClaude Codeのどちらかが動く状態が必要です。Windows環境やLinuxサーバーでは2026年9月時点では動きません。

インストールは2行です。

uv tool install codealmanac@latest
codealmanac setup

setup は対話形式で進みます。急ぐなら --yes で推奨値のまま入ります。実行役（runner）の既定はCodexで、Claude Codeを使うなら明示します。

codealmanac setup --yes                    # 既定（Codexを実行役にする）
codealmanac setup --yes --runner claude    # Claude Codeを実行役にする

ここで混同しやすい引数があります。--target は「どのツール向けのグローバル指示ファイルを置くか」を決めるだけで、実行役の選択ではありません。実行役は --runner 側。ここを取り違えると「設定したのに動かない」に見えます。

setup が入れるものは2種類です。ひとつは選んだツール向けのエージェント指示ファイル。もうひとつがmacOS標準の定期実行の仕組み（launchd）で登録される定期タスク3本です。

設定の途中で、匿名の利用状況送信について聞かれます。公式の説明では、送るのはコマンドの成否と異常終了の記録だけで、コード・パス・引数・検索語・指示文・会話ログ・認証情報は送らず、位置情報の推定も無効。気になるなら setup --no-telemetry か DO_NOT_TRACK=1 で止められます。社内規程が厳しいなら、ここは最初にオフにしておくのが無難です。

導入自体は5分で終わります。手間がかかるのはこの後。

---

導入手順2: initで最初のwikiを立ち上げる

対象リポジトリに移動して、初期化と読み取りを試します。

cd your-repo
codealmanac init                     # wikiが無ければ作る
codealmanac search "getting started" # 該当ページを探す
codealmanac show getting-started     # 1ページをターミナルで開く
codealmanac serve                    # ローカルのビューアで見る

init はキューに積まれたジョブとしてローカルのワーカーが処理します。すぐ終わるとは限りません。進行を見たいなら codealmanac serve を立ち上げてサイドバーの Jobs を開くか、ターミナル派なら codealmanac jobs attach <run-id> で追いかけます。

ここで大事な注意が公式に明記されています。ライフサイクル系のコマンドは、信頼済みのローカルエージェントを、非対話でファイルシステムに広く触れる権限のまま動かします。almanac/ に限定するのは指示とコミット方針であって、OSレベルの隔離ではありません。

ここまでの整理: CodeAlmanacは「入れる」までは2コマンドですが、「動かす」時点でエージェントに広い権限を渡します。試すなら、まず捨ててよい検証用リポジトリから。本番の資産リポジトリでいきなり回すのは避けたほうが賢明です。

自動コミットを切っておくと、変更をdiffで確認してから自分でコミットできます。

codealmanac setup --no-auto-commit
codealmanac config set auto_commit false

最初の1回は、これで様子を見るのが安全です。

---

導入手順3: ingestで既存の資産を流し込む

init で骨格ができたら、既にある材料をwikiへ折り込みます。担当するのが ingest です。

codealmanac ingest README.md --using codex
codealmanac ingest github:pr:123 --using claude

受け付ける入力の幅が、このツールの本体価値です。整理するとこうなります。

つまり、PRのレビューコメントに埋もれていた「この設計にした理由」を、AIが次回から読める場所へ引き上げられます。実務でいちばん効くのはここ。レビュー議論は普段どこにも再利用されていません。

材料に持続的な価値がなければ、wikiを変更しないまま終わるのが正しい動作だと公式は明言しています。何も起きなかった場合に不具合を疑わないでください。

そして garden が、貯まったページの手入れをします。古くなったページ、弱いリンク、重複、根拠のない記述を見直す役です。

codealmanac garden --using codex

---

syncとgardenは何を自動でやってくれる？

setup が登録する定期タスク3本が、放っておいてもwikiを回します。既定のスケジュールは次のとおりです。

つまり、あなたが今日AIと交わした議論が、その日のうちにwikiの候補として拾われます。「メモを取る」という人間側の習慣に依存しない設計です。

間隔の変更や停止は設定コマンドで行えます。

codealmanac automation status                       # 入っているスケジュールを見る
codealmanac config set automation.sync.every 5h     # 間隔を変える
codealmanac config set automation.sync.enabled false # 止める

設定ファイルは ~/.codealmanac/config.toml にあり、直接編集した場合は codealmanac config apply を忘れずに。反映されないまま悩む定番の落とし穴です。

ログは ~/.codealmanac/logs/ に出ます。クラウドには何も上がりません。

---

読む側のコマンドと、ローカルビューア

書く仕組みばかり注目されますが、日常的に触るのは読み取り側です。人間もAIも同じコマンドを使います。

codealmanac search "checkout timeout"
codealmanac search --mentions src/checkout/
codealmanac show checkout-flow
codealmanac topics
codealmanac health
codealmanac validate

--mentions が地味に効きます。特定のファイルやディレクトリに言及しているページを引けるので、「このファイルを触る前に読むべき注意書き」が一発で出ます。

codealmanac serve で立ち上がるビューアは読み取り専用です。ページ、検索、トピック、被リンク、ファイル参照のたどりが見られます。ヘッドレスで使うなら --no-open。読み取り系のコマンドはAIの認証を必要としないので、チームの非エンジニアにも渡しやすい部分です。

書き込み系はそうはいきません。選んだ実行役が使える状態で認証済みであることが条件になります。

codex login
claude auth login
codealmanac doctor

doctor が実行役の状態を診断してくれます。困ったら最初にこれ。

---

料金はいくらかかる？

CLI本体は無料です。Apache-2.0のオープンソースで、PyPIから配布されています。有料プランやライセンス購入という概念がありません。

ただし、実質的な費用はゼロではありません。wikiを書く作業はCodexかClaude Codeが実行するので、その利用枠を消費します。

つまり、既にCodexかClaude Codeを契約している開発者にとって、追加の固定費なしで始められます。逆に、どちらも契約していないなら、そこの費用が入口になります。

ここで注意点がひとつ。Claude系の料金体系は2026年6月中旬に見直されており、対話的に使うターミナル上のClaude Codeはサブスクリプション枠、Agent SDK経由の実行は月次クレジット扱いという二本立てになっています。CodeAlmanacのClaude実行はYokeの既定であるPython Agent SDK面を通るため、どちらの枠を食うかは自分の契約で確認してから回し始めるのが安全です。

自動化を全部オンにしたまま放置すると、5時間おきにエージェントが動き続けます。最初は --sync-off で手動運用から入り、消費量を見てから自動化を足す。この順番を推奨します。

料金設計そのものを含めて開発環境のコストを見直したい人は、AI活用の初期費用の考え方も参考になります。

---

他のAIコーディング環境とどう組み合わせる？

CodeAlmanacはエディタでもコード生成AIでもありません。既存の環境の下に敷く「文脈の層」です。だから競合ではなく前提として考えます。

つまり、実行役はCodexかClaude Codeの二択ですが、出来上がったwikiはただのmarkdownなので、どのツールからでも読めます。ここが賢い設計です。

Codexをまだ触っていないなら、Codexの基本操作とCodexの導入と設定を先に通しておくと、実行役の挙動で迷いません。ローカルのモデルで開発を回している人は、OllamaとClaudeの併用の記事が環境設計の参考になります。補完中心の使い方を比べたい場合はCodeiumの解説もどうぞ。

---

導入前に知っておきたい落とし穴

先に潰しておくと後が楽です。実運用で刺さりやすい順に4つ挙げます。

• macOS以外では動かない: CIサーバーや共有Linuxマシンでの常時運用は、2026年9月時点では選択肢に入りません
• エージェントの権限は広い: almanac/ への限定は指示レベル。機密度の高いリポジトリでは自動コミットを切ってdiff確認を挟むこと
• npm版は死んでいる: 旧codealmanac npmパッケージは提供終了。古い環境が残っていると衝突するので、npm uninstall -g codealmanac してからPyPI版を入れる
• wikiは資産だがノイズにもなる: 放置して増えたページは、AIを迷わせる側に回ります。garden と validate を回して痩せさせる運用がセット

もうひとつ、チーム運用での本音を書いておきます。almanac/ の変更がPRに混ざると、レビューの手間が増えます。AIが書いた文章のレビューを誰が引き受けるのか、ここを決めずに導入すると1か月で誰も見なくなります。運用ルールの設計が、導入作業より重い。

---

AI PICKS編集部の判定

構想としては圧倒的に筋がいいです。AIコーディングの品質が伸び悩む原因を「モデルの賢さ」ではなく「渡している文脈の欠落」に置き、その解決策をリポジトリ内のmarkdownとGitのレビューに落とし込んだ設計は、公開情報を突き合わせた限りかなり真っ当な発想に見えます。記憶をベンダーのサーバーに預ける方式と違い、退会しても資産が手元に残る点も重宝します。

一方で、いま全チームに勧められるかというと、正直そこは微妙です。macOS限定で実行役もCodexとClaude Codeの二択。CIに組み込めないので、チーム全体の共通基盤にはまだなりません。エージェントに広いファイル権限を渡す前提も、機密性の高い環境では引っかかります。

現時点の推奨は「個人またはコアメンバー数人が、自分のMacで検証リポジトリから始める」の一択。無料で試せてロックインもないので、リスクは時間だけです。会話ログから知識が自動で溜まる感触が掴めたら、そこからチームに広げるかを判断すれば十分間に合います。

---

よくある質問（FAQ）

Q. CodeAlmanacは無料で使えますか？

CLI本体はApache-2.0のオープンソースで、利用料はかかりません。費用が発生するのは、wikiを書くAIを動かす側、つまりCodexやClaude Codeの契約分だけです。

Q. WindowsやLinuxで動きますか？

2026年9月時点では動きません。公式が対応環境として明示しているのはmacOSのみで、自動化の仕組みにもmacOS標準のlaunchdを使っています。ただし出来上がった almanac/ はただのmarkdownなので、他OSのメンバーがGitHub上で読むことは問題なくできます。

Q. CursorやGitHub Copilotを使っていても意味がありますか？

あります。実行役としては使えませんが、wikiは通常のmarkdownファイルとしてリポジトリに置かれるので、どのエディタからでも参照できます。AIに読ませるコンテキストの置き場として機能します。

Q. 会社のコードが外部に送信されませんか？

wikiの生成と索引作成はすべてローカルで動き、ホスト型の同期サービスは存在しません。ただしwikiを書く処理自体はCodexやClaude Codeが担うため、コードはそれらのサービスの経路を通ります。取り扱い基準は、既に使っているコーディングAIの規程に準じます。任意の利用状況送信はコードやパスを含まない仕様で、オフにもできます。

Q. 既存の社内wikiやNotionと二重管理になりませんか？

なる可能性はあります。切り分けの目安は「コードの近くにあるべきか」。設計判断や不変条件はリポジトリ側に置き、営業資料や組織情報は既存のwikiに残すのが現実的です。ingest はURLも受け付けるので、既存ドキュメントの要点だけ折り込む使い方もできます。

Q. wikiが増えすぎて逆に邪魔になりませんか？

その懸念に対する機能が garden です。24時間ごとに古いページ、重複、つながりの弱い記述を見直します。codealmanac health と codealmanac validate で状態を点検する習慣を付けておくと崩れにくくなります。

Q. 何から試すのが安全ですか？

捨ててよい検証用リポジトリで codealmanac setup --no-auto-commit から入るのが安全です。自動コミットを切っておけば、AIが書いた内容をGitのdiffで全部確認してから取り込めます。公式リポジトリは github.com/AlmanacCode/codealmanac にあります。

---

あわせて見たいツール・カテゴリ

• Claude Code: CodeAlmanacの実行役に指定できる2つのうちの片方。ターミナル前提の開発ならこちら
• Codex: 既定の実行役。設定を触らずに始めたいならまずこれ
• Cursor: エディタ側の主力。almanac/ を読ませる先として組み合わせやすい
• Cline: VS Code上でエージェント的に動かしたい人向け
• AIコーディングツールのカテゴリ: 開発支援AIを横断して見比べる入口
• AIコーディングツールの評価一覧: 機能と条件を並べて絞り込みたいとき
• AIエージェントのカテゴリ: 自律的に作業するAI全般を押さえたい場合

次に読むならこれ。実行役をまだ決めていないなら、Codexの導入と設定から入ってください。CodeAlmanacの設定で迷う箇所の大半は、実行役側の認証と権限の理解で消えます。

各ツールの公式サイト（一次情報）

料金・機能・対応範囲は各社公式が一次情報です。本記事は公開時点の検証に基づきますが、最新かつ正確な条件は必ず各公式ページで確認してください。

• Claude Code — 公式サイト（AI PICKSの詳細）
• OpenAI Codex — 公式サイト（AI PICKSの詳細）
• Cursor — 公式サイト（AI PICKSの詳細）
• GitHub Copilot — 公式サイト（AI PICKSの詳細）