Slack MCP Agent — フォルダ構成

v1.3 / 2026-04-20

MVP のディレクトリレイアウトと命名規約を定義する。
docs/architecture.md のレイヤー構成、DESIGN.md Section 8.3 のコンポーネント構成と整合。

---

1. ルートディレクトリ

slack-mcp-agent/
├── backend/                 # Python: Slack Bot + Pipeline + Custom Tool（ユニットテスト同梱）
├── web/                     # TypeScript: Next.js 管理画面
├── mcp-servers/             # Python: MCP Server（単体起動・テスト用）
├── shared/                  # Python: Backend / MCP 共有コード + shared/tests/
├── scripts/                 # セットアップ・ユーティリティスクリプト（OAuth、seed、combined MCP）
├── docs/                    # 設計ドキュメント
├── data/                    # SQLite DB ファイル (gitignore)
├── raw/                     # 要求資料 (PDF, Excel)
├── outputs/                 # 分析メモ (gitignore 推奨)
├── .cursor/                 # Cursor IDE 設定（Rules / Skills）
├── .github/                 # GitHub Actions
├── DESIGN.md                # デザイン指示書
├── AGENTS.md                # AI 開発ルール
├── Makefile                 # 開発コマンド一括管理
├── Dockerfile               # Railway デプロイ用 (マルチステージ)
├── nginx.conf               # nginx リバースプロキシ設定テンプレート
├── start.sh                 # コンテナエントリーポイント
├── .dockerignore            # Docker ビルド除外ルール
├── pyproject.toml           # Python ルートプロジェクト (uv workspace)
├── .env                     # 環境変数 (gitignore)
├── .env.example             # 環境変数テンプレート
├── .gitignore
└── README.md

> MVP では統合テスト・E2E テストを専用ディレクトリに分離せず、各パッケージの `*/tests/` 配下にユニットテスト + 軽量な E2E（例: `backend/tests/test_pipeline_e2e.py`）を集約している。

---

2. Backend

backend/
├── src/
│   ├── __init__.py
│   ├── app.py               # Slack Bolt App ファクトリ、main()
│   ├── config.py             # 環境変数 → Settings dataclass
│   │
│   ├── pipeline/             # L1-L4 パイプライン
│   │   ├── __init__.py
│   │   ├── orchestrator.py   # handle_mention: L1+L2 フロー制御
│   │   ├── l1_task.py        # Message → Task JSON
│   │   ├── l2_prompt.py      # Task → Prompt テキスト
│   │   ├── l3_process.py     # Prompt → Steps JSON
│   │   └── l4_session.py     # Steps → Managed Agent Execution
│   │
│   ├── tools/                # Custom Tool Executor (MVP 新規)
│   │   ├── __init__.py
│   │   ├── router.py         # tool_name → executor ルーティング
│   │   ├── freee_client.py   # freee API Client (OAuth, retry)
│   │   ├── freee_adapter.py  # freee Response → Shared Schema 変換
│   │   └── schemas.py        # Shared Schema dataclass (Employee, Attendance)
│   │
│   ├── slack/                # Slack イベント・アクション
│   │   ├── __init__.py
│   │   ├── events.py         # app_mention, assistant_thread_started
│   │   ├── actions.py        # approve/reject/cancel/retry ハンドラ
│   │   └── cards.py          # Block Kit JSON ビルダー
│   │
│   ├── models/               # データモデル (SQLite CRUD)
│   │   ├── __init__.py
│   │   ├── database.py       # get_connection, migrate, isonow
│   │   ├── enums.py          # StrEnum (TaskStatus, PromptStatus, ...)
│   │   ├── tenant.py
│   │   ├── task.py
│   │   ├── prompt.py
│   │   ├── process.py
│   │   ├── execution.py
│   │   ├── slack_message.py
│   │   ├── audit_log.py      # MVP 新規
│   │   ├── settings.py       # MVP 新規
│   │   ├── integration.py    # MVP 新規
│   │   └── tool_permission.py
│   │
│   └── prompts/              # System Prompt ファイル
│       ├── l1_system.md
│       ├── l2_system.md
│       ├── l3_system.md
│       └── skills/           # Post-MVP: Managed Agents Skills
│           ├── hr-attendance-rules.md
│           ├── hr-payroll-logic.md
│           └── ...
│
├── tests/                    # Backend ユニットテスト
│   ├── __init__.py
│   ├── conftest.py           # pytest fixtures (DB, mock clients)
│   ├── test_l1_task.py
│   ├── test_l2_prompt.py
│   ├── test_l3_process.py
│   ├── test_l4_session.py
│   ├── test_actions.py
│   ├── test_cards.py
│   ├── test_tools/           # Custom Tool テスト
│   │   ├── test_router.py
│   │   ├── test_freee_client.py
│   │   └── test_freee_adapter.py
│   └── test_models/          # モデル CRUD テスト
│       ├── test_task.py
│       └── ...
│
└── pyproject.toml            # Backend 依存: slack-bolt, anthropic, aiosqlite, ...

---

3. Web (管理画面)

web/
├── app/
│   ├── globals.css           # CSS Variables + Tailwind (DESIGN.md 準拠)
│   ├── layout.tsx            # RootLayout: font, ThemeProvider
│   ├── (dash)/               # 認証必須の管理画面グループ
│   │   ├── layout.tsx        # DashShell: サイドバー + メイン
│   │   ├── page.tsx          # / → パイプライン一覧
│   │   ├── pipeline/
│   │   │   └── [id]/
│   │   │       └── page.tsx  # /pipeline/[id] → パイプライン詳細
│   │   ├── settings/
│   │   │   └── page.tsx      # /settings → 設定
│   │   ├── integrations/
│   │   │   └── page.tsx      # /integrations → 外部連携
│   │   └── audit/            # Post-MVP
│   │       └── page.tsx      # /audit → 監査ログ（未実装）
│   └── api/
│       └── integrations/
│           └── freee/
│               ├── auth/
│               │   └── route.ts   # freee OAuth 開始
│               └── callback/
│                   └── route.ts   # freee OAuth コールバック
│
├── components/
│   ├── ui/                   # shadcn/ui コンポーネント (自動生成)
│   │   ├── badge.tsx
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── collapsible.tsx
│   │   ├── input.tsx
│   │   ├── select.tsx
│   │   ├── switch.tsx
│   │   ├── table.tsx
│   │   └── toast.tsx
│   ├── dash-shell.tsx        # サイドバーレイアウト
│   ├── status-badge.tsx      # ステータスバッジ
│   ├── pipeline-table.tsx    # パイプラインテーブル
│   ├── timeline-view.tsx     # タイムラインビュー (詳細画面)
│   ├── integration-card.tsx  # 接続カード
│   └── theme-toggle.tsx      # ダーク/ライト切替
│
├── lib/
│   ├── db.ts                 # better-sqlite3 接続ヘルパー
│   ├── utils.ts              # cn() 等のユーティリティ
│   └── actions.ts            # Server Actions (設定保存等)
│
├── middleware.ts              # Basic 認証
├── next.config.ts
├── tailwind.config.ts
├── tsconfig.json
├── package.json
└── pnpm-lock.yaml

---

4. MCP Servers

mcp-servers/
├── hr-freee/                 # HR ツール単体起動用 (port MCP_HR_FREEE_PORT, 既定 8001)
│   ├── server.py             # FastMCP エントリーポイント
│   ├── tools/                # list_employees / list_attendance / calculate_overtime
│   └── pyproject.toml
│
└── common/                   # 汎用ツール単体起動用 (port MCP_COMMON_PORT, 既定 8002)
    ├── server.py             # FastMCP エントリーポイント
    ├── tools/                # write_rows_to_google_sheet / send_slack_dm
    └── pyproject.toml

MVP の make dev では上記 2 サーバーを起動せず、scripts/combined_mcp_server.py を単一プロセスで起動する（docs/architecture.md §2.1 参照）。hr-freee / common は単体ユニットテストや個別動作確認用。

---

5. Shared

shared/
├── schemas/
│   ├── __init__.py
│   ├── employee.py           # Employee dataclass
│   ├── attendance.py         # AttendanceRecord dataclass
│   └── payroll.py            # OvertimeSummary dataclass
├── tests/
│   ├── __init__.py
│   └── test_schemas.py
└── pyproject.toml            # shared パッケージ

Backend と MCP Server の両方から参照可能な共通コード。ルート pyproject.toml のワークスペース定義（path dependency）で管理。

---

6. Scripts

scripts/
├── setup-managed-agent.py    # Anthropic Agent/Environment 作成
├── setup-freee-oauth.py      # freee OAuth 手動トークン取得
├── seed-test-data.py         # 開発用: DB にテストデータを投入
├── seed-manifest.json        # seed 用データ定義
├── test_l4_manual.py         # L4 手動疎通確認スクリプト
├── simulate-action.py        # E2E 動作確認: Slack ボタン操作のシミュレーション
├── docs-prebuild.sh          # MkDocs 用にルート Markdown を docs/_root/ に同期
└── combined_mcp_server.py    # 開発用: hr-freee + common を統合した単一プロセス MCP Server

make dev は scripts/combined_mcp_server.py を起動する。ngrok は make dev の一部として ngrok http --domain=$NGROK_DOMAIN 8001 で実行される。

---

7. Tests

MVP では統合テスト・E2E テスト専用ディレクトリを設けず、パッケージ付随の */tests/ に寄せている。

tests/
├── integration/              # 統合テスト
│   ├── test_pipeline_e2e.py  # L1 → L2 → L3 → L4 一気通貫
│   ├── test_approval_flow.py # 承認/却下/再生成フロー
│   └── test_freee_api.py     # 実 freee API テスト (CI 除外)
│
├── e2e/                      # E2E テスト (Playwright)
│   ├── package.json          # @playwright/test, tsx 依存
│   ├── tsconfig.json
│   ├── playwright.config.ts  # baseURL, httpCredentials, chromium のみ
│   ├── admin/                # 管理画面テストスペック
│   │   ├── smoke.spec.ts     # 全ページ到達可能性テスト
│   │   ├── pipeline.spec.ts  # パイプライン一覧/詳細
│   │   └── settings.spec.ts  # 設定画面
│   └── utils/
│       └── browser.ts        # アドホック検証用統合ユーティリティ
│
└── fixtures/                 # テスト用固定データ
    ├── task_samples.json
    ├── prompt_samples.json
    └── freee_responses/      # freee API モックレスポンス
        ├── employees.json
        └── work_records.json

backend/tests/                # Backend のユニット + 軽量 E2E
├── conftest.py, helpers.py
├── test_l1_task.py / test_l2_prompt.py / test_l3_process.py / test_l4_session.py
├── test_orchestrator.py / test_events.py / test_actions.py / test_cards.py
├── test_models.py
├── test_pipeline_e2e.py       # L1 → L2 → L3 → L4 の軽量 E2E（モック）
└── test_tools/                # Custom Tool Executor のユニットテスト

shared/tests/
└── test_schemas.py            # Shared Schema のユニットテスト

mcp-servers/*/tests/           # 各 MCP Server 単体のツールテスト

Post-MVP: tests/ をルートに新設し、Playwright 等による Web の E2E や、実 freee API テスト（CI 除外）を集約予定。

---

8. Docs

docs/
├── requirements.md           # 要求定義書
├── mvp-spec.md               # MVP 要件定義書
├── mvp-requirements.md       # (旧版、参照用)
├── slack-ui-spec.md          # Slack UI カード仕様書
├── admin-ui-spec.md          # 管理画面仕様書
├── architecture.md           # システムアーキテクチャ
├── tech-decisions.md         # 技術選定 (ADR)
├── data-model.md             # データモデル設計
├── custom-tools.md           # Custom Tool 設計
├── prompt-design.md          # プロンプト設計
├── project-structure.md      # フォルダ構成 (本書)
├── error-handling.md         # エラーハンドリング設計
└── post-mvp-roadmap.md       # Post-MVP 課題リスト

---

9. 命名規約

9.1 Python

要素	規約	例
パッケージ	snake_case	pipeline, models, tools
モジュール	snake_case	l1_task.py, freee_client.py
クラス	PascalCase	TaskStatus, FreeeAdapter
関数	snake_case	run_l1(), handle_mention()
定数	UPPER_SNAKE	SCHEMA_VERSION, POLL_INTERVAL_SECONDS
dataclass	PascalCase	Employee, AttendanceRecord
テスト	test_ prefix	test_l1_task.py, test_l1_output_schema()

9.2 TypeScript (Web)

要素	規約	例
コンポーネント	PascalCase	StatusBadge, PipelineTable
ファイル名	kebab-case	status-badge.tsx, pipeline-table.tsx
ページ	page.tsx (App Router 規約)	app/(dash)/page.tsx
Server Actions	camelCase	updateSettings()
CSS Variables	kebab-case	--status-generating
型	PascalCase	Task, PipelineRow

9.3 ファイル共通

要素	規約	例
ドキュメント	kebab-case.md	data-model.md, tech-decisions.md
環境変数	UPPER_SNAKE	SLACK_BOT_TOKEN, ANTHROPIC_API_KEY
DB テーブル	snake_case (複数形)	tasks, prompts, audit_logs
DB カラム	snake_case	tenant_id, created_at
Git ブランチ	feature/, fix/, chore/	feature/l4-custom-tools

---

10. gitignore ルール

# データ
data/
*.db
*.db-wal
*.db-shm

# 環境
.env
.venv/
__pycache__/
node_modules/

# IDE
.cursor/projects/

# ビルド
.next/
dist/

# OS
.DS_Store

---

変更履歴

日付	バージョン	変更内容
2026-04-18	v1.0	初版作成
2026-04-20	v1.1	scripts/simulate-action.py 追加、tests/e2e/ Playwright 環境追加
2026-04-20	v1.2	Dockerfile, nginx.conf, start.sh, .dockerignore をルートに追加 (issue #31)
2026-04-20	v1.3	実装整合を反映。shared/schemas/ 構造・scripts/ の実際のファイル・combined MCP 方針・web/login の未実装化・監査ログ UI の Post-MVP 扱い・docs-prebuild.sh を追記