Claude CodeやCodexで開発していると、毎日同じ壁にぶつかります。エージェントは「なぜこの設計になっているか」「過去に何が壊れたか」を知らない。コードには現在の形しか書かれていないからです。

私は名古屋でAIシステム開発の会社(株式会社エクスブリッジ)をやっています。社内では十数個のプロダクトをClaude Codeで開発・運用していますが、正直に言うと、エージェントに同じ説明を三回した週がありました。「そのポートは本番で使っている」「その設定は前に事故った」——会話で説明した文脈は、会話が終わると消えるのです。

この問題への回答が、Y Combinator発のオープンソース「CodeAlmanac」(Apache-2.0・GitHubスター約1,000)です。リポジトリの中にmarkdownの「生きたwiki」を持ち、エージェントとの会話から知識を自動で収穫・手入れします。設計判断の理由、障害の記録、守るべき不変条件が、コードと一緒にGitで管理される。エージェントは作業前にそれを読む。

ただし、日本のチームがそのまま使うには2つの壁があります。

1つ目は環境です。公式は現状macOS専用(バックグラウンドジョブがlaunchd依存)。当社はLinux対応(systemdユーザータイマー)を実装して本家にプルリクエスト(#73)を提出済みで、マージ前でも動かす手順を確立しています。

2つ目は「何を書くか」です。ツールを入れても、wikiに何をどう書けばエージェントが従うのかは、ツールは教えてくれません。当社が全プロジェクトで実運用して固めた書式——1ページ1事実、「なぜ」を書く、実測値を書く、禁止事項は理由とセット——があって初めて機能します。

この記事(有料部)は、その両方を1つにまとめた導入・運用キットです。

■内容(15ファイル分の全文)

・導入手順: macOS(公式)/Linux(systemd・PR #73系)の両対応

・Claude Code連携: セットアップと、CLAUDE.mdに足す指示文サンプル

・日常操作リファレンスとトラブルシュート(実測ベース)

・本体=「日本語wikiの書式設計」: 当社実運用の原則

・雛形5点: 判断記録・障害記録・不変条件・ワークフロー・用語集

・チーム運用: レビューへの組み込み、「書かれない知識」を減らす3つの仕掛け

■こんな方に

・Claude Code/Codexを業務導入していて、同じ説明を繰り返している

・属人化した設計判断を、人にもAIにも引き継げる形にしたい

・CodeAlmanacに興味はあるがmacOS専用で止まっていた

動作環境: Python 3.12以上 / uv / Claude CodeまたはCodex / macOSまたはLinux(systemd)。

同じ内容はKurage App Store(https://kappstore.exbridge.jp/app.php?id=b81d730eb535b454)でも買い切り5,500円で販売しています。Brainでの購入も内容は同一です。