Claude Codeに手探りで聞きながらAIデスクの土台を作った日
mano
manote diary
CLAUDE.md運用day2、決めきれなかったことばかりの一日
mano
CLAUDE.mdとは、AIエージェントに開発ルールを理解させるための設定ファイルのこと。今回は、この運用設計に迷いまくった2日目の記録だよ。
昨日はGit導入とか環境構築とか、手を動かす作業が中心だった。今日はその続きで、AIデスクのCLAUDE.md運用を仕上げる回。手を動かすというより、決め事を整理する一日だったと思う。
途中まで進めて気づいたのは、今日やったことのほとんどが「決めた」というより「一旦こうしておく」で止まっているということ。knowledge/index.mdの分類基準も、docs/rules/への分割も、組織構造の比喩も、どれも「今のところはこれで」というトーンで終わっている。
その場では違和感なく決めたつもりでも、後から見返すと「これでいいのかな」と思う箇所がいくつかあった。今日はその迷いをそのまま書いておこうと思う。
Contents
開発ログの避難とknowledge ディレクトリ整理を進めた話
開発ログをブログから分離してknowledge/daily/へ集約し、過去の経緯はGit履歴に任せてarchive/を作らない整理を行った。
今日やったのは、blogとknowledge/daily、Git履歴という3つの置き場所に役割を分ける作業だった。これまでGit導入や環境構築みたいな開発ログをblog/に置いてたんだけど、それをknowledge/daily/へ移動した。blogは公開用の完成原稿だけにする、という切り分けだね。
ブログ領域を完成原稿のみに絞りログを移動する
もし開発ログをそのままblogに残していたら、後で読み返す人は公開記事なのか作業メモなのか区別がつかなくなる。逆にdaily側にまとめておけば、あとで特定のトピックへ統合するときに迷わず拾い出せる感じかな。
開発ログって最初からナレッジに入れとけばよかったんじゃないの？
それが最初はblogに書いてたんだよね。あとで読み返して『これ公開する記事じゃないな』って気づいた感じ！
手順としては、まず「今日の内容をKnowledgeへ反映して」という指示で、dailyログをトピック別のknowledge/*.mdへ統合する中間ステップを追加した。
archiveフォルダを作らずGit履歴に任せる選択
archive/フォルダは作らない、という方針も確認した。過去の経緯はGitの履歴を見れば追えるから、というのが理由なんだよね。
knowledge/
├── daily/ # 開発ログ（一時的な記録）
├── index.md # トピック一覧の目次
└── *.md # トピック別に統合したナレッジCLAUDE.md 運用の可読性を高めるため7つの番号を付与した
冒頭にファイルの適用範囲を明文化し、絶対ルールに番号を振ることで可読性と管理性を向上させた。
実際にやったのは2点だけ。CLAUDE.mdの冒頭に定義文を置くことと、絶対ルールに番号を振ることだった。
冒頭にファイル自体の定義を一文で添える
冒頭に「複数プロジェクトへ影響する共通ルールのみを書く」という一文を足した。これは今後何か追記するかどうか迷ったときの判断基準になるね。
これで『このルールはCLAUDE.mdに書くべきか』を毎回考えなくて済みますね
そうそう、複数プロジェクトに関係するかどうかだけ見ればいいから楽になった！
複数プロジェクトへ波及する共通ルールのみを残す
7つの絶対ルールには1〜7の番号を振った。もし番号がなければ、後から「あの決まりって何番目だっけ」と探す手間が毎回発生する。番号があれば会話の中でも「ルール7に沿って」とすぐ指せるかも。
| 項目 | 変更前 | 変更後 |
|---|---|---|
| ブログとログの扱い | blog/に開発ログを混在 | knowledge/daily/へ移動、blogは完成原稿のみ |
| ナレッジ目次作成基準 | 10〜20ファイルで分類検討 | 一覧性が低下したと感じたら判断 |
| ファイル分割判断 | 検討事項として認識 | 現状は分割せずCLAUDE.mdへ集約 |
| 報告ラインの通信 | 未実装 | ユーザーが手動で伝令 |
index.mdの目次ルールを数値から感覚へ変えた迷い
目次作成の閾値を固定のファイル数から「一覧性の低下」という感覚的な判断に変えたが、基準の曖昧さは残っている。
「10〜20」という数字を捨てて、感覚に頼る運用へ切り替えた。ここが今日いちばん決めきれなかった箇所なんだよね。
10〜20ファイルという機械的な閾値の限界
当初は「トピックファイルが10〜20個になったら目次を作る」って決めてたんだけど、これをやめた。ファイル数だけで区切るなら、中身が薄い10ファイルでも機械的に目次を作る羽目になる。逆に20ファイルを超えていても見渡せていると感じるなら、まだ作らなくていい場合もあるよね。
じゃあ結局いつ目次を作ればいいの？
それが『一覧性が下がったと感じたら』にしたんだよね
それって人によって感じ方違わない？
うん、そこはまだちゃんと答えられてないかな……
一覧性の低下を判断基準にする曖昧さ
客観的に測れる指標があるかと言われると、わからない。ファイルを開く回数とか、探すのにかかった時間とか、そういう数字で見る方法もあるのかもしれないけど、今日の時点ではそこまで詰めていない感じ。
docs rules 分割のタイミングを見送った曖昧な基準
将来的なルールファイルの分割可能性を認識しつつも、現時点では時期尚早としてCLAUDE.md内への保持を選択した。
CLAUDE.md本体にルールを収めたまま、docs/rules/への分割は未定のまま脇に置いた。
肥大化を防ぐ分割提案と時期尚早という判断
docs/rules/へルールを分割する案自体は認識していた。ただ「今はまだ早い」という理由で見送った。今CLAUDE.mdに全部書いたままにしておけば、当面は読む場所が1つで済む。逆に肥大化が進んで探しにくくなったタイミングで分けるなら、そのときにあらためて構成を考えることになる。
あとで調べたら、CLAUDE.mdが100行を超えたら@インポートや.claude/rules/へ分割するという運用パターンを紹介している記事もあった。Cursorのルールファイルでも50行を超えたら分けるという話があるらしい。ただ、うちの今の分量にそのまま当てはめていいのかは判断してないんだよね。
いつ分割に踏み切るかという未解決の課題
行数なのか、ルールの種類なのか、それとも読みにくさを感じた瞬間なのか。今日の時点ではどれも決めてない。
『時期尚早』ってことは、いつか分けるつもりではあるんだよね？
そのつもり。でもその『いつか』の条件がまだ決まってなくて！
AIデスク 組織構造を持株会社とCEOに例えてみる
AIデスクを指示と管理に専念する持株会社、個々の開発を子会社に見立てる比喩で役割分担を整理した。
持株会社・CEOとしてのAIデスクを上に、複数の子会社としてのプロジェクトを下に置く形で整理してみた。
コードを書かずに全体調整へ専念する役割
AIデスクはコードを書かない。方針・優先順位・調整・共通知識の管理に専念する、という比喩でイメージを整理した。各プロジェクトは実装・設計・テスト・TODO・Knowledgeに集中する個別の子会社、という位置づけだね。
持株会社は現場に手を出さず、方針だけ渡すという理解でよろしいですか
そうそう、その感じ。実際どこまでうまく当てはまるかはまだわからないけど！
もしAIデスクが方針だけを持てば、各プロジェクトは自分の中で実装判断を完結できる。逆にAIデスクが細かい実装にまで口を出すなら、そもそも子会社と呼ぶ意味がなくなってしまうかも。
個別子会社としてのプロジェクト群という比喩
この比喩がどこまで実態に合っているかは、正直まだ自信がない。今日はイメージを言語化しただけで、検証はこれからになるね。
AIエージェント ルールの報告ラインを人間が渡り歩く現実
自動連携経路がないため、特定の重要変更が起きた際のAIデスクへの報告・伝令を人間が手動で媒介する設計にした。
プロジェクトとAIデスクの間に立って、伝令として動くのは今のところ人間の役目になっている。
アーキテクチャ変更時のみ発生する報告条件
「AIデスクへの報告」ルールも新設した。アーキテクチャ変更・新規プロジェクト・共通テンプレート変更・セキュリティ・コスト・他プロジェクトへの影響、このどれかに該当する場合だけ、理由と推奨アクションをセットにしてユーザーへ通知する形にした。
アーキテクチャ変更のような大きい話なら報告する。逆に普段の実装の細かい調整まで毎回報告していたら、報告そのものがノイズになってしまうよね。
自動通信経路がないため伝令役をユーザーが担う
今のところプロジェクト間・プロジェクトとAIデスク間を自動でつなぐ経路はない。だから「伝令」を人間が担う設計にしている。
エージェント同士が勝手に連携するようになったらこの役目いらなくなるんじゃない？
経路が自動化されても報告の基準自体は変えないつもりでいるよ。今はまだそこまで先の話じゃないから、実際どうなるかはわからないな
CLAUDE.md 書き方における全体ルールと個別ルールの境界
ルールの重複記載による矛盾を防ぐため、正本の一元化とインポート記法による階層分離が重要となる。
ルールの「正本」を1箇所に置いて、各プロジェクトからはそこを参照する形にしたい、という話。
ユーザー領域の設定とプロジェクト固有設定
複数プロジェクトに関わるルールならCLAUDE.md本体に書く。逆にそのプロジェクトだけの話なら、そっちのプロジェクト側に置くべき、という線引きにした。
以前読んだQiitaの記事に、ルールは行動が起きる場所の近くに書いて、理由と代替行動を添えるとよいという話があった。今回の線引きもそれに近い発想だと思う。
記述の重複を避けて一元管理を保つ難しさ
同じルールを複数箇所に書くと、内容がズレたときにどっちが正しいのか分からなくなる。正本を1箇所に決めて、他からは参照する形にしておきたいけど、今日の時点では「そうしたい」というところまでしか固めてない感じ。
最初のプロジェクトでルール一式を試す前に残る違和感
構築したルール一式を実プロジェクトで試す段階に入ったが、手動運用の限界や基準の揺らぎという課題は未解決のままである。
曖昧さや手動の負担というハードルを抱えたまま、実地検証のスタートラインに立つことになる。
次にやることは決まっていて、実際に最初のプロジェクトを1つ作って、今日までに整えたルール一式――dustbox・OS非依存・daily/knowledge/blogの3層・自動コミットフック・報告ルール――を実地で試すことになる。
ただ、それを試す前の時点で、まだ答えが出ていないことがいくつも残っている。index.mdの目次を作るタイミングを感覚で判断していいのか。docs/rules/への分割はどのくらい肥大化したら踏み切るのか。持株会社とCEOという比喩が実際の運用にどこまで耐えるのか。どれも今日中に片付く話ではなかったな。
実地でうまく回るなら、このままの基準でも問題ないのかもしれない。逆にどこかで詰まる場面が出てきたら、そのとき初めて基準を見直すことになるんだろうと思う。今の時点ではそのどちらになるかはまだわからない感じだね。
ABOUT ME
2025/11/20
厄年なのかなんなのか色々起きて超どん底に。人生で初めて本気で起業しようと決意！元"ねらー"のサーチ力と持ち前の好奇心、今までの知識をフル活用して1,6万円から本気で起業を目指す！