転職用のポートフォリオとして、個人でWebアプリ「Hubpin」を作っています。
制作の経緯は「Hubpin 開発記録」に時系列でまとめています。
設計と判断は自分で行い、実装も原則自分で書いています。AIには手順書・レビュー・調査を任せています。
作業ルールや学習ログを、全部Markdownのファイルで管理しています。
gitで履歴を持たせて、AIエージェントに読ませる運用です。
これが特定のツールへの依存になっているのではないか、と気になっていました。
実際 CLAUDE.md というファイル名は Claude Code しか読みません。
そこで、Notion や Obsidian にデータベースを作って全部集約する運用に切り替えるべきか検討しました。
結論から書くと、やめました。 依存先が移るだけだと分かったからです。
きっかけ: ツールごとに読む設定ファイルが違う
エディタの乗り換えを検討していて気づいたことがあります。
AIコーディングツールは、それぞれ別の設定ファイルを読みます。
| ツール | 読む設定ファイル |
|---|---|
| Claude Code | CLAUDE.md |
| Cursor | .cursor/rules |
| Codex ほか多数 | AGENTS.md |
自分は運用ルールを全部 CLAUDE.md 側に書いています。
案件の工程をNotionに記録する、設計判断を残す、発信できそうなネタをマーカーで拾う、といったものです。
別のツールで作業すると、これらが一切適用されません。作業自体は進みますが、ログが空白になります。
自分にとっては記録のほうが資産なので、これは地味に痛い。
同じフォルダの中に、文脈を共有しない2つのAI環境が同居する形になります。
「両方使えばいいじゃん」で済まないのは、運用ルールが実装ではなく設定ファイルに乗っているからでした。
ツールを増やすとルールも複製が必要になり、二重管理が発生します。
そこで考えたこと: 外部DBに逃がせばいいのでは
ファイル名がツールに紐づいているのが問題なら、ツールの外に出せばいい。
Notionにデータベースを作って、MCP経由でどのAIからも読めるようにする。
一見きれいな解決に見えました。
比べたら、交換条件が良くなかった
| Markdown + Git | 外部DB | |
|---|---|---|
| どのAIでも読めるか | ファイルなので普遍 | MCP/API 経由が必要 |
| grep・全文検索 | 効く | 弱い |
| 履歴・差分・巻き戻し | Gitがある | ほぼない |
| AIから読むコスト | ほぼゼロ | レイテンシとトークンが乗る |
| スマホから見る | できない | できる |
| 他人と共有・同時編集 | できない | できる |
Notionに寄せれば、Notionの仕様変更・料金改定・APIレート制限を受けます。リスクの種類が変わるだけで、量は減りません。
そして表を見て分かったのは、外部DBの強みは「共有」と「スマホ」であって、ポータビリティではなかったことでした。
自分が求めていたのはポータビリティ。目的と手段がずれていました。
規模が違う人のやり方を真似ると起きること
これが今回いちばんの学びです。
チーム運営なら、外部DB集約は必然になります。 同時編集・権限管理・引き継ぎは、人が増えた瞬間に必須コストになるので。
だから「ドキュメントはNotionに集約すべき」と書いている人は正しい。
でも一人でやっている場合、その最大の便益がまるごと効きません。 共有相手がいないので。残るのは、AIから読むときのコスト増だけです。
事業規模が違う人のやり方をそのまま真似ると、便益の部分だけ落ちて、コストの部分だけ残ることがある。今回がそれでした。
「ベストプラクティス」を採用するときは、それが誰の前提で書かれているかを見ないといけないな、と思いました。
もうひとつ: 依存していると思っていたものが、そこまで深くなかった
検討していて気づいたことがあります。
仮に明日、使っているAIが変わったとして、自分が失うものは何か。
- スキルの起動方法
- フックのイベント名
- ファイル名（
CLAUDE.mdという名前そのもの）
これくらいでした。中身はぜんぶMarkdownなので残ります。
器を作り直すだけで済む。「ツールに依存している」という感覚は、実際の依存度より大きく見積もられていました。
依存が怖いときは、具体的に何を失うのかを書き出してみるのが効くと思います。書き出すと、思ったより少ないことが多い。
AGENTS.md という選択肢
補足として、ツール非依存の標準もあります。
AGENTS.md は OpenAI発です。
いまは Linux Foundation の Agentic AI Foundation（MCPと同じ場所）が管理しています。
Codex・Cursor・GitHub Copilot・Gemini CLI など、主要なツールが対応しています。
ただし Claude Code はネイティブでは読みません。
GitHub に要望のissueが立っていますが、いまのところ対応の予定は示されていません。CLAUDE.md からインポートするか、シンボリックリンクを張る必要があります。
自分はいまのところ片方に寄せる方針にしました。ルールを持つほうを母艦にして、別ツールは補完として使う。
標準に寄せるのは、実際に複数ツールを常用するようになってからでいいと判断しています。
まとめ
- AIツールはそれぞれ別の設定ファイルを読む（
CLAUDE.md/.cursor/rules/AGENTS.md） - 依存を避けようと外部DBへ寄せても、依存先が移るだけでリスクの量は減らない
- 外部DBの強みは「共有」と「スマホ」。一人だとその便益が効かない
- 規模が違う人のやり方は、便益だけ落ちてコストだけ残ることがある
- 「依存している」と感じたら、具体的に何を失うか書き出す。思ったより少ない
一人でやっているうちはファイルとgitで足りて、人が増えたら外部DBが必要になる。規模によって最適解が変わるというだけの話でした。
どちらが正しいかではなく、いま自分がどっち側にいるかを見て決めればよさそうです。
