Claude Code と Agentic AI による作業のための壁打ち
Q：私
あなた・エージェンティックAIとのやり取りのため、一旦必要そうなフォルダ階層やマークダウンファイルを配置してみました。 Q:あなたにとって初手の段階でファイルや説明がある程度揃っていたほうが良いのか、またはゼロベースで私とステップバイステップでフォルダ作成などを行ったほうが「あなたにとって」都合が良いのはどちらになりますか？
A：Claude Code
良い質問です。正直に答えます。
「ファイルがある程度揃っている」ほうが都合が良いです
理由：
1. コンテキスト把握の効率 私はコードベースを探索するツールを持っていますが、ファイルが存在しない場合は「何もない」という情報しか得られません。ファイルがあれば、既存の構造・命名規則・パターンを読み取り、それに沿った提案ができます。
2. 一貫性の維持 フォルダ階層や命名が先に決まっていれば、私が生成するコードや提案がそれに合わせて一貫したものになります。ゼロから一緒に作ると、私が後から「実はこの構造のほうが良かった」と気づいても変更コストが増します。
3. 仕様ドキュメントの参照 あなたが docs/specs/ に仕様を書いてくれていれば、私は実装前にそれを読んで意図を正確に把握できます。口頭説明だけより誤解が少ない。
ただし注意点
- ファイルが多すぎると探索に時間がかかる（エージェントの並列探索で対処できますが）
- 仕様が不明確なままファイルだけ作られても、誤った前提で進む可能性があります
推奨
現在のように「フォルダ階層 + 仕様マークダウン」を先に用意していただく形が最も効率的です。特に docs/specs/ 以下に仕様を書いてもらえると、私が実装計画を立てる際の根拠として直接参照できます。
仕様書と1回あたりの作業フローは別で管理したほうがあなたにとっては良いのかなと考えています。ベストプラクティスがあれば教えて下さい。
良い判断です。分離することを推奨します。
推奨構造
docs/
├── specs/ # 仕様書（変化が少ない・永続的）
│ ├── README.md # 仕様の概要・索引
│ └── editors/
│ └── callbacks.md
└── tasks/ # 作業指示（1回ごとに使い捨て or 更新）
└── current.md # 今やること
そして CLAUDE.md に以下を明記：
# IMPORTANT
1. まず docs/specs/README.md を読む（仕様・制約）
2. 次に docs/tasks/current.md を読む（今回の作業内容）分離する理由
| 仕様書 | 作業指示 | |
|---|---|---|
| 更新頻度 | 低い | 毎回変わる |
| 私の使い方 | 実装の制約確認 | 何をすべきか把握 |
| 粒度 | 詳細・網羅的 | 具体的・絞られている |
作業指示ファイルに書くべき内容
# 今回の作業
## ゴール
○○を実装する
## スコープ（触って良いファイル）
- src/editors/xxx.ts
## スコープ外（触らないこと）
- src/core/ 以下
## 完了条件
- [ ] ○○が動くスコープ外の明示が特に重要です。私は「改善できそうな箇所」を見つけると手を広げがちなので、明示的に制限してもらうと余計な変更を防げます。
Q：私
了解しました。コンテキストの記録（次回セッションに継ぐためのもの）のベストプラクティス・慣習はありますか？
A：Claude Code
セッション間コンテキスト引き継ぎのベストプラクティス
基本的な考え方
私はセッションをまたいで記憶を保持しません。毎回ゼロスタートです。ただし CLAUDE.md を読むことは保証されている ので、そこを起点にします。
推奨構造
docs/
├── specs/ # 仕様（永続）
├── tasks/
│ ├── current.md # 今回やること
│ └── log/ # 過去の作業ログ（任意）
│ └── 2026-02-17.md
└── context/
└── progress.md # ← 引き継ぎファイル
docs/context/progress.md に書く内容
# 現在の状態
## 完了済み
- xxx の実装完了（src/editors/xxx.ts）
## 未完了・途中
- yyy のコールバック処理（仕様は docs/specs/editors/callbacks.md 参照）
- 懸念点：○○の挙動が未確定
## 次回セッションの最初にやること
1. src/editors/xxx.ts を確認
2. yyy の実装を続けるCLAUDE.md への記載
# IMPORTANT
1. docs/specs/README.md を読む
2. docs/context/progress.md を読む（現在の進捗・未解決事項）
3. docs/tasks/current.md を読む（今回の作業）実用的なポイント
- 私に書かせる — セッション終了前に「progress.md を更新して」と依頼するのが最も確実です。私が作業内容を把握した状態で書くので正確です
- 簡潔に — 長すぎると私が読むコストが増えます。箇条書き中心で
- 懸念・未確定事項を必ず残す — 「なぜこうしたか」の判断根拠が特に重要です
Q：私
progress.md について、その都度都度追記していくことになるかと思います。作業を繰り返していくうちにこのファイルは肥大化していき、あなたが読み取って把握するにも許容から溢れてしまうと推察します。この場合は人間側である程度の区切りのタイミングで別ファイル名で保持しておくというようなことが良いのでしょうか？このあたりの慣習・ベストプラクティスがあれば教えて下さい。
A：Claude Code
良い観点です。いくつかのアプローチがあります。
推奨：2層構造にする
docs/context/
├── progress.md # ← 常に「今」だけを書く（軽量に保つ）
└── archive/
├── 2026-01-xx.md
└── 2026-02-xx.md
progress.md の設計思想を変える
「累積ログ」ではなく「現在のスナップショット」として使う
# 現在の状態（2026-02-17 更新）
## アーキテクチャの現状
- xxx は完了。src/editors/xxx.ts に実装済み
## 未完了
- yyy のコールバック処理
## 重要な判断・制約（なぜそうなっているか）
- ○○はあえて△△方式にしている。理由：□□
## 次回やること
1. yyy の続き完了したものは 消す。アーカイブに移す必要があるほどの情報は基本的に 仕様書に昇格させる のが正しい流れです。
情報の「昇格」フロー
progress.md（一時的）
↓ 重要な決定・設計判断は
docs/specs/ に移す（永続化）
↓ 完了した作業ログは
archive/ に移す（参照用）
目安となるサイズ感
progress.mdは 50行以内 を目標にする- 超えてきたら整理のタイミング
- アーカイブは私が読む必要はないので、サイズ制限不要
実用的な運用
セッション終了時に私に依頼する内容：
「progress.md を更新して。完了済みのものは消して、仕様として固まった内容は docs/specs/ の適切な場所に移して」
こうすることで、整理も私がやるので人間側の負担が最小化されます。
Q：私
これまでのあなたのアドバイスを下にファイル整備をしてみました。これは作業依頼ではなく構造やマークダウンの内容評価依頼です。
A：Claude Code
全体の評価をまとめます。
総評：よくできています
構造の考え方は適切で、私が毎回必要なものが過不足なく揃っています。ただし、いくつか具体的な指摘があります。
指摘事項
1. パスのタイポ（重大）
CLAUDE.md の2行目：
docs/context/progress.md ← context（単数）
実際のフォルダは：
docs/contexts/progress.md ← contexts（複数）
私がこのパスを読もうとすると「ファイルが存在しない」と判断してスキップします。
2. docs/README.md が参照されなくなっている（重大）
現在の CLAUDE.md は3ファイルしか指定していませんが、docs/README.md にはプロジェクト概要・シンボル種別・フォルダ階層・JSTルール・作業フローが書かれています。
これが読まれないと、私はプロジェクトの背景を把握できません。
対処案A：CLAUDE.md に docs/README.md を先頭に追加する 対処案B：docs/README.md の内容を docs/specs/README.md に統合する
3. 読み取り順序の矛盾（軽微）
| ファイル | 順序 |
|---|---|
| CLAUDE.md | specs → progress → current |
| docs/README.md 作業フロー | current → specs → progress |
統一してください。私の推奨は current → specs → progress です（「何をするか」を先に把握してから仕様・文脈を読む）。
4. tasks/current.md の書式にスコープ外が未定義（軽微）
以前推奨した「触らないこと」の項目が書式テンプレートにありません。追加を検討してください。
## スコープ外（触らないこと）
- xxx良い点
archives/とlogs/は「AI側からの参照は不要」と明記されている → 的確- 各ディレクトリにREADMEがある → 良い習慣
- YAMLスキーマが整備されている → 仕様の根拠が明確
Q：私
１つ質問です。
- xxx この「スコープ外」についての解説をお願いします。
A：Claude Code
スコープ外（触らないこと）とは
私は作業中に「改善できそうな箇所」を見つけると、依頼されていない変更を加えることがあります。
例：
「variable エディタを実装して」と依頼された場合
私が作業中に src/core/parser.ts にバグを発見したとします。依頼の範囲外ですが、「ついでに直しておこう」と判断して変更することがあります。
これが問題になる理由：
- あなたが意図しない変更が入る
- レビューコストが増える
- 「どこが変わったか」が追いにくくなる
- 最悪、別の動作を壊す
スコープ外の書き方
## スコープ外（触らないこと）
- src/core/ 以下のファイル
- docs/specs/ のファイル（読むのはOK、変更はしない）
- variable エディタ以外のエディタ実装このように明示されていると、私は「ここは触ってはいけない」と判断して抑制します。
どんな時に特に重要か
- リファクタリングや大きな機能追加の時
- 複数エディタが並行して存在する時
- 「今回はこれだけやる」という境界を明確にしたい時
逆に小さな作業（1ファイルのみ）の場合は省略しても構いません。
理解しました。フィードバックを修正したので再度評価をお願いします。
Read CLAUDE.md
Read README.md
Read README.md
前回の指摘事項との比較評価です。
修正確認
| 指摘事項 | 状態 |
|---|---|
パスのタイポ（context → contexts） | 修正済み |
docs/README.md が参照されない | 修正済み（CLAUDE.md の1番目に追加） |
tasks/current.md にスコープ外を追加 | 修正済み |
| 読み取り順序の矛盾 | 後述 |
残存する問題
1. tasks/README.md のテンプレート内に説明文が混入（重大）
docs/tasks/README.md:39-44 を見ると、コードブロック（テンプレート）の中に「など」以下の説明文が入り込んでいます。
など
- リファクタリングや大きな機能追加の時 ← これはテンプレートではなく説明
- 「今回はこれだけやる」という...
逆に小さな作業（1ファイルのみ）の場合は省略してもOK。これはコードブロックの外に出すべき注記です。私がこのテンプレートをそのまま解釈すると、current.md の書式として誤認します。
2. 読み取り順序の矛盾（軽微）
| ファイル | 読む順序 |
|---|---|
| CLAUDE.md | README → specs → progress → current |
| docs/README.md 作業フロー | current → specs → progress |
CLAUDE.md はセッション開始時の「オンボーディング順」、docs/README.md は「作業実行順」として意図が異なるなら問題ありませんが、同じものを指しているなら統一が必要です。意図を確認させてください。
総評
前回の重大な問題はすべて対処されています。上記1点の修正で実用上の問題はほぼなくなります。
Q：私
明確な作業フローの定義が存在していなかったので良かれと思って記載を行いましたが、CLAUDE.md でのオンボーディング内容であなたが同じ作業フローをセッションごとに確立できる、ということであれば追記した作業フローセクションは削除しますがどうでしょうか？
A：Claude Code
削除は推奨しません。理由を説明します。
作業フローセクションの内訳
現在のセクションには2種類の性質が混在しています。
| ステップ | 内容 | CLAUDE.md でカバー済み？ |
|---|---|---|
| 1〜3 | 読む順序 | はい（重複） |
| 4〜7 | 作業後の行動（確認依頼・ログ記入・progress更新） | いいえ |
重要なのはステップ4〜7
4. 作業を行う
5. 作業結果内容の確認依頼をする
6. tasks/logs/YYYY-MM-DD.md に作業内容のログを記入する
7. contexts/progress.md に作業結果内容を反映させる
これらは私が作業後に何をすべきかを定義しています。この指示がないと、私は実装を終えた時点で「完了」と判断し、ログ記入や progress.md の更新を自主的には行いません。
推奨
ステップ1〜3を削除してCLAUDE.mdに一本化し、ステップ4〜7は残す形が最もすっきりします。
## 作業フロー
1. 作業を行う
2. 作業結果内容の確認依頼をする
3. 確認完了後、tasks/logs/YYYY-MM-DD.md に作業ログを記入する
4. contexts/progress.md に作業結果を反映させるQ：私
理解しました。調整しましたので再評価してください。
A：Claude Code
評価
docs/README.md ✅ 問題なし
作業フローが「作業後の行動」のみになり、CLAUDE.md との重複・矛盾が解消されています。
docs/tasks/README.md — 軽微な点が1つ残存
テンプレート内（コードブロック）の スコープ外 セクションが実例値になっています：
## スコープ外（触らないこと）
- src/core/ 以下のファイル ← 実例
- docs/specs/ のファイル（読むのはOK...） ← 実例他のセクションは ＜タスクA＞ のようにプレースホルダー形式です。ここだけ揃えると一貫性が出ます：
## スコープ外（触らないこと）
- ＜触らないファイルやモジュール＞実例は直後の「スコープ外（触らないこと）について」セクションに既にあるので、テンプレート内はプレースホルダーだけで十分です。
総評
前回の指摘はすべて対処されています。残るのは上記1点のみで、機能上の問題ではなく可読性の話です。全体として実用に耐えるドキュメント構成になっています。
Q：私
理解しました。調整しましたので再評価してください。
A：Claude Code
問題ありません。
テンプレート内がプレースホルダー（＜触らないファイルやモジュール＞）に統一され、実例は「について」セクションに分離されています。構造として明確です。
これまで指摘した全項目が対処されました。ドキュメント基盤として実用上の問題はありません。
Q：私
現状の状態で progress.md はAI側が随時ファイル更新するという解釈になっていますか？
A：Claude Code
はい、その解釈で正しいです。
根拠は docs/README.md の作業フロー ステップ4：
4. contexts/progress.md に作業結果内容を反映させる
この作業フロー全体が私への指示として書かれているため、progress.md の更新も私が行うものと解釈します。
ただし、現状のドキュメントには1点曖昧さがあります。
docs/contexts/README.md に 「誰が更新するか」 の明記がありません。作業フローを読めば推測できますが、明示されていないため、将来的に混乱する可能性があります。
意図通りなら以下のような一文を追加すると明確になります：
## progress.md について
「累積ログ」ではなく「現在のスナップショット」として使う。
**更新はAI側が作業完了後に行う。**これは必須ではありませんが、ドキュメントの明確さとしての提案です。
Q：私
追記しました！ 同じく tasks/current.md の扱いも似たようなルールを tasks/README.md に記載しましたので合わせて評価してください。
A：Claude Code
両ファイルとも問題ありません。
contexts/README.md — 更新はAI側が作業完了後に行う。 が明記され、曖昧さが解消されています。
tasks/README.md — 人間とAIの役割分担が明確に定義されています：
- タスク作成 → 人間
- チェックボックスのON → AI
1点だけ細かい話として、docs/contexts/README.md:14-15 の2行がMarkdown上で段落が繋がって見える可能性があります：
「累積ログ」ではなく「現在のスナップショット」として使う
**更新はAI側が作業完了後に行う。**改行を入れると視覚的に分かれます。ただしレンダリング環境次第なので必須ではありません。
全体として、これまでの指摘事項はすべて対処されており、ドキュメント基盤として完成度が高い状態になっています。
Q：私
ありがとうございます。箇条書き - で修正しましたが、改行（段落）とであなたにとって解釈の仕方は変わりますか？
A：Claude Code
解釈は変わりません。
私はMarkdownをレンダリング後の見た目ではなく、テキストとして読み取り意味を理解します。箇条書き・改行・段落のいずれであっても、内容が同じであれば同じ意味として解釈します。
ただし箇条書き（-）にしたことで人間が読む際の視認性が上がるので、その点では良い変更です。私への影響はありません。
contexts, tasks のアーカイブファイル（YYYY-MM-DD.md） について、現在の状況ではAI側が作成するという解釈になっていますか？それともあいまいな状況でしょうか？
現状のドキュメントを整理すると、2つのファイルで扱いが異なります。
tasks/logs/YYYY-MM-DD.md → AIが作成と解釈
docs/README.md 作業フロー ステップ3に明記されています：
3. 作業結果内容の確認が完了したら、tasks/logs/YYYY-MM-DD.md に作業内容のログを記入する
contexts/archives/YYYY-MM-DD.md → 曖昧
docs/contexts/README.md には「AI側からの参照は不要」とだけ書かれており、誰が作成するかの記載がありません。作業フローにも対応するステップがありません。
意図の確認
contexts/archives/ の想定運用はどちらですか？
- A: progress.md が肥大化してきたタイミングで人間がアーカイブ移動する
- B: AIが作業完了後に前回の progress.md 内容をアーカイブに退避してから更新する
Aであれば「人間が管理する」とドキュメントに明記するだけで足ります。Bであれば作業フローにステップを追加する必要があります。
Q：私
理想は B ですが、フローへの追記もそうですし、最も重要なのは「アーカイブに堆肥する条件」の確立ができて、セッションに依存しなく再現性の確保と私は考えました。それを踏まえてあなた（エージェンティックAI全般）にとってのベストプラクティスがあれば教えて下さい。
A：Claude Code
良い問いです。核心は「AIが主観なく判断できる条件」の設計にあります。
ベストプラクティス：条件を客観的・定量的に定義する
AIは「肥大化してきた気がする」という判断ができません。必ず数値や状態で条件を定義します。
推奨アーカイブ条件
## アーカイブ条件
progress.md を更新する前に以下を確認し、
いずれかに該当する場合は先にアーカイブを作成する。
1. progress.md が 50行を超えている
2. 人間から明示的にアーカイブを指示された50行は目安です。プロジェクト規模に応じて調整してください。
アーカイブ時のファイル名ルール
## アーカイブファイル名
contexts/archives/ に保存するファイル名は、
progress.md のヘッダーに記載されている「最終更新日時（JST）」を使用する。
例: 「# 現在の状態（2026-02-18 14:30 更新）」→ 2026-02-18.md現在日時ではなく進捗の日付を使うことで、内容と名前が一致します。
作業フローへの追記（推奨）
docs/README.md の作業フローに以下を追加：
1. 作業を行う
2. 作業結果内容の確認依頼をする
3. 確認完了後、tasks/logs/YYYY-MM-DD.md に作業ログを記入する
4. contexts/progress.md を更新する前にアーカイブ条件を確認する
- 条件を満たす場合：現在の progress.md を archives/YYYY-MM-DD.md として保存してから更新
- 条件を満たさない場合：そのまま更新再現性が確保される理由
- 条件が行数という数値なので、どのAIセッションでも同じ判断になる
- ファイル名のルールが一意に決まる（ヘッダーの日付から導出）
- 人間側の操作は「明示的な指示」のみ（任意）
Q：私
反映しました。再評価をお願いします。
A：Claude Code
概ね良好です。2点指摘します。
1. contexts/README.md 45行目：孤立したテキスト
docs/contexts/README.md:45 に
アーカイブ時のファイル名ルール
という行が、見出しでも箇条書きでもないプレーンテキストとして残っています。直後の ### アーカイブファイル名 と内容が重複しているため、削除で問題ありません。
2. docs/README.md 60行目：パスが曖昧
docs/README.md:60：
現在の progress.md を archives/YYYY-MM-DD.md として保存
archives/ だけでは contexts/archives/ を指すのか不明瞭です。フルパスで記載することを推奨します：
現在の progress.md を contexts/archives/YYYY-MM-DD.md として保存
それ以外は問題ありません。アーカイブ条件（300行）・ファイル名ルール（ヘッダー日付から導出）ともに明確で再現性のある定義になっています。
Q：私
2点修正しました。再度評価をお願いします。
A：Claude Code
両方の修正を確認しました。
contexts/archives/YYYY-MM-DD.mdとフルパスに修正済み- 孤立テキスト削除済み
指摘事項はすべて解消されています。現時点でドキュメント基盤に問題はありません。