コンテンツにスキップ

エージェント専用ワークスペースのディレクトリ設計#

Techniques #workspace #organization #directory updated 2026-04-13 5 min read

エージェントに仕事を任せる際、作業する専用のディレクトリ構造を設計すると、混乱が減り、追跡性が上がる。「ワークスペース」という発想で整理する。

基本構造#

flowchart TD
    W[workspace/] --> T[tasks/<br/>タスクごとのフォルダ]
    W --> D[docs/<br/>参照ドキュメント]
    W --> O[output/<br/>生成物]
    W --> L[logs/<br/>実行ログ]
    W --> M[MEMORY.md]

    T --> T1[task-2026-04-14-xxx/]
    T --> T2[task-2026-04-15-yyy/]

    T1 --> P[prompt.md]
    T1 --> R[result.md]
    T1 --> LOG[log.md]

各ディレクトリの役割#

tasks/ — 1 タスク 1 フォルダ

  • prompt.md: エージェントへの指示（何をしてほしいか）
  • result.md: 成果物
  • log.md: 試行錯誤の経緯
  • diffs/: 生成された変更

docs/ — エージェントが参照すべきドキュメント

  • 関連する ADR
  • コーディング規約
  • タスクの背景情報

output/ — 長期保管する生成物

  • コード、ドキュメント、画像 等
  • 完成版のみを置く（試行は tasks/ に残す）

logs/ — 実行ログ

  • 各タスクの実行結果サマリ
  • エラー・失敗の記録

MEMORY.md — エージェントが参照する外部記憶

  • セッションをまたいで保持したい決定
  • よくある質問と回答
  • 避けるべき振る舞い

なぜこの構造か#

1. 追跡性

「この変更は誰が何のために作ったか」を後から追える。

2. 再現性

同じタスクを再実行したいとき、prompt.md と docs/ があればほぼ再現できる。

3. 引き継ぎ

別のエージェントや人間が途中から引き継ぐとき、workspace を見れば状況が掴める。

4. 失敗から学ぶ

log.md に試行錯誤を残すと、同じ罠を踏まずに済む。

運用のフロー#

sequenceDiagram
    participant H as 人間
    participant A as エージェント
    participant W as workspace

    H->>W: tasks/task-XXX/prompt.md 作成
    H->>A: タスク開始を指示
    A->>W: log.md に試行記録
    A->>W: result.md に成果
    A->>W: 必要に応じて output/ へ保管
    H->>W: 内容確認 + フィードバック
    A->>W: MEMORY.md 更新

タスクディレクトリの命名#

tasks/
  2026-04-14-auth-refactor/
  2026-04-14-add-logging/
  2026-04-15-bug-investigation/

日付 + kebab-case タスク名。時系列で並ぶので追いやすい。

避けるべきパターン#

1. ファイルが散乱する

ルートに notes.md, old.md, tmp.md が増える。必ず tasks/ 配下に入れる。

2. ドキュメントが古い

docs/ が更新されないまま放置。参照する前に最新化するか、日付を書く。

3. ログが巨大化

log.md が 1000 行超え。タスク完了時に要約して、詳細はアーカイブへ。

4. MEMORY.md の肥大化

何でも書いて膨らむ。決定事項のみに絞り、詳細は ADR へ。

スケーラビリティ#

タスクが増えたら:

  • 週次アーカイブ: tasks/archive/2026-W15/ へ移動
  • 月次棚卸し: 古いタスクの成果物を output/ に昇格、ログを削除
  • 検索: ripgrep 等で横断検索

運用のコツ#

flowchart LR
    S[タスク開始] --> P[prompt.md 作成]
    P --> E[エージェント実行]
    E --> R[result.md 保存]
    R --> F[フィードバック]
    F --> M[MEMORY.md 更新]
  • prompt.md は必ず先に書く。口頭指示だけで始めない
  • result.md で完了を明示。未完なら「未完」と記載
  • 週次で MEMORY.md を棚卸し。古い決定は削除 or ADR 化

チェックリスト#

  • [ ] workspace/ 直下に tasks/, docs/, output/, logs/, MEMORY.md がある
  • [ ] タスクは日付 + 名前のフォルダに分ける
  • [ ] prompt.md を必ず書く
  • [ ] 完了したら result.md でまとめる
  • [ ] 学びは MEMORY.md に反映
  • [ ] 週次でアーカイブ・棚卸し

まとめ#

エージェント専用のワークスペース設計は、追跡性・再現性・引き継ぎを劇的に改善する。1 タスク 1 フォルダの原則を守るだけで、混乱がなくなる。

関連エントリ#