Local Directory Guide

本ガイドでは、AI エージェントおよび開発者の作業領域・記憶領域となる .local/ ディレクトリの役割、内部構成、連携スキル、および運用ルールについて解説します。

概要

<root>/.local/ は、Git のバージョン管理対象外（.gitignore）として定義された、ローカル環境専用の作業領域および記憶・記録領域です。

AI エージェントが作業中に出力する一時ファイルや提案書、タスク定義、さらに作業を通じて得られた失敗・教訓・知見や作業日報を安全に保存・蓄積するために利用されます。リポジトリ本体のファイルを汚すことなく、エージェントの自律的な作業と知識の永続化を両立します。

主な役割

• 作業領域 (Workspace / Scratch): 一時的なタスク定義（tasks.toml）、中間データや出力差分の作成・実行場所。

• 作業計画・手順領域 (Workplan): 具体的な作業手順（STEP-<ID>）、作業記録、作業メモの一時的な管理領域（workplan/）。

• 提案書領域 (Proposals): プロジェクトやテンプレートの改善提案書（<topic>-proposal.md）の管理領域（proposals/）。

• 記憶・記録領域 (Memory & Worklog): 開発中に判明した知見・失敗・教訓の蓄積（memory/）、セッションごとの作業日報や残作業の集約（worklog/）。

• ローカル専用リソース (Docs & Resources): リポジトリにコミットしない非公開の検証データや参照資料の保管。

---

ディレクトリ構成

<root>/.local/ 配下の標準的なディレクトリ構成と役割は以下の通りです。

<root>/.local/
├── artifacts/                  # 一時的な生成成果物（画像・データ変換出力等）
├── docs/                       # ローカル専用ドキュメント・参照資料
│   └── raw/                    # 非追跡の正本データ・外部資料
├── logs/                       # 実行ログ・ツールログの保管領域
├── memory/                     # 失敗・教訓・重要知見の記録領域
│   ├── index.tsv               # メモリー総合台帳
│   └── YYYYMMDD-<name>.md      # 個別メモリーファイル
├── proposals/                  # 改善提案書管理領域 (write-proposal)
│   └── <topic>-proposal.md     # 改善提案書
├── resources/                  # ローカル検証用アセット・リソース
├── worklog/                    # 作業日報・残作業管理領域
│   ├── index.tsv               # 作業日報総合台帳
│   ├── todo.md                 # 引き継ぎ残作業集約ファイル
│   └── YYYYMM/                 # 年月別ディレクトリ
│       └── YYYYMMDD-<topic>.md # 個別作業日報ファイル
├── workplan/                   # 作業計画ノート管理領域 (write-workplan)
│   └── <name>.md               # 個別作業計画ノート
└── workspace/                  # 一時作業領域 (<workspace>)
    └── tasks.toml              # 一時 mise タスク定義

---

各ディレクトリの役割と詳細

1. workspace/ (一時作業領域 <workspace>)

AI エージェントのスクラッチ領域であり、指示書上で <workspace> として参照されるディレクトリです。

• 一時タスク定義 (tasks.toml): 作業中のみ使用する使い捨てコマンドや検証処理を create-mise-task スキルにより定義します。
• スクラッチファイル: Git 差分出力、一時スクリプト、データ変換の中間ファイル等を配置します。

2. memory/ (記憶・ナレッジ蓄積領域)

会話や作業を通じて得られた、既存ドキュメントに含まれていない重要な知識、失敗、トラブルシューティング事例、ベストプラクティスを永続化する領域です。

• 個別メモリー (YYYYMMDD-<name>.md): 発生事象、根本原因、得られた知見、再発防止策・行動指針を構造化して記録します。
• メモリー台帳 (index.tsv): 作成されたすべてのメモリーを日付・概要・ファイル名で一覧管理する TSV 形式の台帳です。
• 主な連携スキル: write-memory スキルを用いて作成・台帳更新を行います。

3. worklog/ (作業日報・残作業管理領域)

セッションごとの作業内容や進捗を日報として記録し、次回以降に引き継ぐべき残作業を一元管理する領域です。

• 個別日報 (YYYYMM/YYYYMMDD-<topic>.md): そのセッションで実施した作業内容、関連ファイル、発生した問題点・懸念事項を記録します。
• 作業日報台帳 (index.tsv): すべての日報を降順（最新が先頭）で一覧管理する TSV 形式の台帳です。
• 残作業集約 (todo.md): 各日報から未完了の残作業を集約し、章立てで詳細と関連日報リンクを管理します。
• 主な連携スキル: write-worklog スキルを用いて日報作成、台帳更新、残作業更新を行います。

4. workplan/ (作業計画ノート管理領域)

作業の手順（How）と作業記録・メモを一時的に管理する領域です。docs/ 配下の仕様や docs/plan.md（戦略）に対し、作業時に必要な具体的実行手順と結果記録を保持します。

• 個別作業計画ノート (<name>.md): 目標、手順（STEP-<ID>(<STATUS>): <description>）、作業記録、作業メモの4章で構成されます。
• 運用ルール: 手順に従って作業を進め、完了時に DONE に更新して作業記録を追記します。手順変更が必要な場合は、TODO ステータスの手順のみ を再作成します。
• 主な連携スキル: write-workplan スキルを用いて作成・手順更新・記録を行います。

5. proposals/ (改善提案書管理領域)

プロジェクト運用中に得られた知見やテンプレート改善案をまとめた提案書を管理する領域です。

• 改善提案書 (<topic>-proposal.md): 本文および変更差分（Diff）を含む標準フォーマットの提案書です。
• 主な連携スキル: write-proposal スキルを用いて作成します。

6. artifacts/ (一時成果物領域)

ツールやスクリプトによって生成された一時的な画像ファイル、エクスポートデータ、変換結果などを配置します。

7. logs/ (ログ保管領域)

ツールの実行結果ログや各種検証ログを一時的に保存します。

8. docs/ および resources/ (ローカル専用資料・リソース)

Git リポジトリ本体にはコミットしない、ローカル検証専用の参照ドキュメントや大容量アセットデータを格納します。

---

連携エージェントスキル

.local/ 配下のファイルは、主に以下のエージェントスキルを通じて作成・更新されます。エージェントは直接手動操作するのではなく、スキル規約に従って整合性を保ちながら運用します。

---

運用ルールと注意事項

• Git 管理からの完全除外: .local/ 配下のファイルはすべて .gitignore の対象です。リポジトリにコミットしないでください。

• スキルの積極的な活用: メモリーや作業日報、作業計画ノートの作成・更新は、専用スキル（write-memory, write-worklog, write-workplan）を使用して整合性を維持してください。

• 一時ファイルの整理: <workspace> 配下に作成した一時的なスクラッチファイルは、作業完了時に不要であれば削除または整理してください。

• パス指定のルール: エージェントへの指示や設定ファイル内では、プロジェクトルートからの相対パス（.local/workspace/）またはスラッシュ（/）区切りのパス表記を使用してください。

---

関連ドキュメント

• directory-structure.md: プロジェクトの標準ディレクトリ構成および配置規則
• mise-guide.md: 一時タスクを含む mise タスクの定義・運用ガイド
• aidev-template-guide.md: テンプレート概要および提案書によるフィードバック手順