スキル統合アーキテクチャ

1. 概要

Issue Outsource Platform では、業務委託エンジニアが Claude Code と既存スキルを組み合わせて開発を行う。本ドキュメントでは、既存スキル群（dev-workflow / multiAgentManageRule / create-docs 等）とプラットフォームの統合ポイント、自動化フロー、テンプレート設計を定義する。

2. スキル統合アーキテクチャ図

mermaid

graph TB
    subgraph "Issue Outsource Platform"
        WebApp["Web App<br/>(React + FastAPI)"]
        Webhook["GitLab Webhook<br/>(Issue / MR イベント)"]
        DB["PostgreSQL<br/>(Issue / 報酬管理)"]
    end

    subgraph "GitLab"
        Issues["GitLab Issues<br/>(報酬付きIssue)"]
        MR["Merge Requests"]
        CI["GitLab CI"]
    end

    subgraph "委託エンジニア環境"
        ClaudeCLI["Claude Code CLI"]
        ClaudeMD["CLAUDE.md<br/>(プロジェクト指示)"]

        subgraph "Skills Layer"
            DevWF["dev-workflow<br/>(Issue調査→実装→MR)"]
            MultiAgent["multiAgentManageRule<br/>(並行開発管理)"]
            CreateDocs["create-docs<br/>(ドキュメント生成)"]
        end

        subgraph ".claude/"
            AgentDefs[".claude/agents/<br/>(エージェント定義)"]
            Settings[".claude/settings.local.json<br/>(権限設定)"]
        end
    end

    Issues -->|"Webhook: issue assigned"| Webhook
    Webhook -->|"通知 → エンジニア着手"| ClaudeCLI
    ClaudeCLI -->|"CLAUDE.md 読み込み"| ClaudeMD
    ClaudeCLI -->|"スキル実行"| DevWF
    ClaudeCLI -->|"並行時"| MultiAgent
    ClaudeCLI -->|"設計書生成時"| CreateDocs
    ClaudeCLI -->|"エージェント定義参照"| AgentDefs
    DevWF -->|"MR 作成"| MR
    MR -->|"CI パイプライン"| CI
    CI -->|"テスト結果"| MR
    MR -->|"Webhook: MR merged"| Webhook
    Webhook -->|"報酬確定"| DB

3. 統合ポイント一覧

統合ポイント	元スキル	Platform側	トリガー
Issue 取得・調査	dev-workflow (`/issue-investigate`)	GitLab Webhook → 通知	Issue アサイン時
実装・MR 作成	dev-workflow (`/issue-implement`)	MR テンプレート自動適用	エンジニア着手時
並行開発管理	multiAgentManageRule	worktree 自動作成	複数 Issue 同時着手時
ドキュメント生成	create-docs	docs/ 配下に自動配置	設計 Issue 着手時
MR レビュー支援	dev-workflow (`/pr-review`)	レビュアー通知	MR 作成時
マージ後テスト	dev-workflow (`/post-merge-test`)	CI パイプライン連携	MR マージ時

4. 自動化フロー詳細

4.1 Issue 取得からMR 作成までの完全フロー

mermaid

sequenceDiagram
    participant Manager as マネージャー
    participant Platform as Platform (Web)
    participant GitLab as GitLab
    participant Engineer as 委託エンジニア
    participant Claude as Claude Code
    participant Skills as Skills Layer

    Manager->>Platform: Issue 作成（報酬設定）
    Platform->>GitLab: Issue 作成 API
    GitLab-->>Platform: Webhook (issue created)
    Platform->>Platform: DB に Issue 登録

    Engineer->>Platform: Issue 一覧閲覧・取得
    Platform->>GitLab: Issue アサイン API
    GitLab-->>Platform: Webhook (issue assigned)
    Platform->>Engineer: Slack/Discord 通知

    Note over Engineer,Claude: === 開発開始 ===

    Engineer->>Claude: claude (CLI 起動)
    Claude->>Claude: CLAUDE.md 読み込み
    Claude->>Skills: /dev-workflow (自動発動)

    Skills->>GitLab: Issue 詳細取得 (API)
    Skills->>Skills: issue-investigate 実行
    Skills->>Claude: 調査結果・実装計画

    Claude->>Claude: git worktree 作成
    Claude->>Skills: issue-implement 実行
    Skills->>Skills: コード実装
    Skills->>Skills: テスト実行
    Skills->>GitLab: MR 作成 (API)
    Skills->>GitLab: Issue コメント（進捗報告）

    GitLab-->>Platform: Webhook (MR created)
    Platform->>Platform: MR と Issue を紐付け

4.2 フロー自動化の実装方針

ステップ	自動化レベル	実装方法
Issue 取得	半自動	Platform UI で取得ボタン → GitLab API でアサイン
worktree 作成	完全自動	`git worktree add` をスクリプト化
Issue 調査	完全自動	dev-workflow `/issue-investigate`
実装	AI 支援	dev-workflow `/issue-implement` + Claude Code
MR 作成	完全自動	dev-workflow がテンプレート適用して作成
報告資料生成	完全自動	mr-report-automation（本設計の別ドキュメント参照）
レビュー依頼	完全自動	Webhook → Platform → 通知

5. CLAUDE.md テンプレート設計

プラットフォームが Issue アサイン時にプロジェクト固有の CLAUDE.md を自動生成する。

5.1 テンプレート構造

markdown

# {プロジェクト名}

## 概要
{プロジェクト概要 - Platform DB から取得}

## 技術スタック
{技術スタック一覧 - プロジェクト設定から取得}

## ディレクトリ構造
{自動生成されたディレクトリツリー}

## コーディング規約
{プロジェクト固有のルール - マネージャーが設定}

## 並行開発ルール
- git worktree で Issue ごとに作業分離
- AGENT_LOG.md を各ステップで更新必須
- GitLab Issue にコメントで進捗報告

## GitLab 連携
- リポジトリ: {リポジトリURL}
- Project ID: {project_id}
- トークン: `security find-generic-password -s "GITLAB_TOKEN" -a "$USER" -w` で取得

## 利用可能なスキル
{プロジェクトで有効化されたスキル一覧}

## 秘密鍵ルール
- トークンを .env に平文で書かない
- macOS Keychain から取得する

5.2 テンプレート変数

変数	データソース	説明
`{プロジェクト名}`	Platform DB: `projects.name`	プロジェクト表示名
`{プロジェクト概要}`	Platform DB: `projects.description`	概要説明
`{技術スタック一覧}`	Platform DB: `projects.tech_stack` (JSON)	使用技術のリスト
`{リポジトリURL}`	GitLab API: `project.web_url`	GitLab リポジトリ URL
`{project_id}`	GitLab API: `project.id`	GitLab Project ID
`{スキル一覧}`	Platform DB: `project_skills`	有効化されたスキル

5.3 自動生成 API

python

# backend/services/claude_md_generator.py

class ClaudeMdGenerator:
    """プロジェクト固有の CLAUDE.md を自動生成する"""

    def generate(self, project_id: int, issue_id: int) -> str:
        project = self.project_repo.get(project_id)
        issue = self.gitlab_client.get_issue(project.gitlab_project_id, issue_id)
        skills = self.skill_repo.get_enabled_skills(project_id)

        template = self.load_template("claude_md_base.md.j2")
        return template.render(
            project=project,
            issue=issue,
            skills=skills,
            coding_rules=project.coding_rules,
        )

6. .claude/agents/ エージェント定義テンプレート

6.1 ディレクトリ構造

.claude/
├── settings.local.json          # 権限設定
└── agents/
    ├── investigator.md          # Issue 調査エージェント
    ├── implementer.md           # 実装エージェント
    ├── reviewer.md              # レビュー支援エージェント
    └── reporter.md              # 報告資料生成エージェント

6.2 investigator.md (Issue 調査エージェント)

markdown

# Issue 調査エージェント

あなたは Issue の調査・分析を行う専門エージェントです。

## 役割
- GitLab Issue の内容を読み取り、要件を整理する
- 既存コードベースを調査し、影響範囲を特定する
- 実装計画を策定する

## 手順
1. GitLab API で Issue 詳細を取得
2. Issue のラベル・マイルストーンを確認
3. 関連する既存コードを Grep / Read で調査
4. 影響範囲と実装方針を AGENT_LOG.md に記載
5. GitLab Issue にコメントで調査結果を報告

## 出力フォーマット
### 調査結果
- **要件概要**: (Issue の要件を1-2文で要約)
- **影響範囲**: (変更が必要なファイル・モジュール一覧)
- **実装方針**: (どのように実装するかの概要)
- **リスク**: (懸念事項・注意点)
- **見積もり**: (想定工数)

6.3 implementer.md (実装エージェント)

markdown

# 実装エージェント

あなたは Issue の実装を行う専門エージェントです。

## 役割
- 調査結果に基づいてコードを実装する
- テストを作成・実行する
- MR を作成して報告資料を添付する

## 手順
1. investigator の調査結果を読み込む
2. feature ブランチで実装を開始
3. コーディング規約に従ってコードを記述
4. 単体テスト・結合テストを作成
5. テストを実行して全てパスすることを確認
6. git commit (適切なコミットメッセージ)
7. MR を作成（テンプレート適用）
8. 報告資料を自動生成して MR に添付

## コミットメッセージ規約
- `feat:` 新機能
- `fix:` バグ修正
- `docs:` ドキュメント
- `refactor:` リファクタリング
- `test:` テスト追加・修正

6.4 reviewer.md (レビュー支援エージェント)

markdown

# レビュー支援エージェント

あなたは MR のレビューを支援する専門エージェントです。

## 役割
- MR の変更内容を分析する
- コード品質・セキュリティの観点でレビューする
- レビューコメントを生成する

## チェック項目
- [ ] コーディング規約の遵守
- [ ] テストの網羅性
- [ ] セキュリティ上の懸念
- [ ] パフォーマンスへの影響
- [ ] ドキュメントの更新
- [ ] 破壊的変更の有無

6.5 reporter.md (報告資料生成エージェント)

markdown

# 報告資料生成エージェント

あなたは MR の報告資料を自動生成する専門エージェントです。

## 役割
- git diff から変更サマリーを生成する
- テスト結果を収集・フォーマットする
- 報告資料テンプレートに沿って資料を作成する

## 出力フォーマット
MR テンプレート (docs/workflows/mr-template.md) に準拠した報告資料を生成する。

## 手順
1. `git diff main...HEAD` で変更内容を取得
2. 変更ファイル一覧と概要を整理
3. テスト実行結果を収集
4. 影響範囲を分析
5. MR テンプレートに沿って報告資料を作成

7. スキル拡張ポイント

7.1 カスタムスキルの追加

プラットフォームでは、プロジェクト固有のカスタムスキルを追加できる設計とする。

Skills/
├── dev-workflow/           # 標準スキル（全プロジェクト共通）
├── multiAgentManageRule/   # 標準スキル
├── create-docs/            # 標準スキル
└── custom/                 # プロジェクト固有スキル
    └── {project-slug}/
        └── SKILL.md

7.2 スキル有効化テーブル

sql

CREATE TABLE project_skills (
    id SERIAL PRIMARY KEY,
    project_id INTEGER REFERENCES projects(id),
    skill_name VARCHAR(100) NOT NULL,
    enabled BOOLEAN DEFAULT true,
    config JSONB DEFAULT '{}',
    created_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(project_id, skill_name)
);

7.3 CLAUDE.md へのスキル自動注入

プロジェクトで有効化されたスキルが CLAUDE.md の 利用可能なスキル セクションに自動的に注入される。

python

def inject_skills_section(project_id: int) -> str:
    skills = get_enabled_skills(project_id)
    lines = ["## 利用可能なスキル\n"]
    for skill in skills:
        lines.append(f"| {skill.name} | {skill.description} | `{skill.path}` |")
    return "\n".join(lines)

8. エラーハンドリングとフォールバック

シナリオ	検知方法	フォールバック
GitLab API 応答なし	HTTP timeout (30s)	リトライ 3回 → エンジニアに手動対応を通知
スキル実行失敗	exit code != 0	エラーログを Issue コメントに投稿 → 手動対応
worktree 作成失敗	git error	既存 worktree のクリーンアップ → 再作成
CLAUDE.md 生成失敗	テンプレートエラー	デフォルトテンプレートを使用
MR 作成失敗	GitLab API error	ドラフト MR として再試行

9. 今後の拡張計画

Phase 1 (現在): 手動スキル実行 + CLAUDE.md テンプレート
Phase 2: Webhook トリガーによる半自動スキル実行
Phase 3: Issue 内容解析 → 最適スキル自動選択 → 完全自動実行

スキル統合アーキテクチャ ​

1. 概要 ​

2. スキル統合アーキテクチャ図 ​

3. 統合ポイント一覧 ​

4. 自動化フロー詳細 ​

4.1 Issue 取得からMR 作成までの完全フロー ​

4.2 フロー自動化の実装方針 ​

5. CLAUDE.md テンプレート設計 ​

5.1 テンプレート構造 ​

5.2 テンプレート変数 ​

5.3 自動生成 API ​

6. .claude/agents/ エージェント定義テンプレート ​

6.1 ディレクトリ構造 ​

6.2 investigator.md (Issue 調査エージェント) ​

6.3 implementer.md (実装エージェント) ​

6.4 reviewer.md (レビュー支援エージェント) ​

6.5 reporter.md (報告資料生成エージェント) ​

7. スキル拡張ポイント ​

7.1 カスタムスキルの追加 ​

7.2 スキル有効化テーブル ​

7.3 CLAUDE.md へのスキル自動注入 ​

8. エラーハンドリングとフォールバック ​

9. 今後の拡張計画 ​

スキル統合アーキテクチャ

1. 概要

2. スキル統合アーキテクチャ図

3. 統合ポイント一覧

4. 自動化フロー詳細

4.1 Issue 取得からMR 作成までの完全フロー

4.2 フロー自動化の実装方針

5. CLAUDE.md テンプレート設計

5.1 テンプレート構造

5.2 テンプレート変数

5.3 自動生成 API

6. .claude/agents/ エージェント定義テンプレート

6.1 ディレクトリ構造

6.2 investigator.md (Issue 調査エージェント)

6.3 implementer.md (実装エージェント)

6.4 reviewer.md (レビュー支援エージェント)

6.5 reporter.md (報告資料生成エージェント)

7. スキル拡張ポイント

7.1 カスタムスキルの追加

7.2 スキル有効化テーブル

7.3 CLAUDE.md へのスキル自動注入

8. エラーハンドリングとフォールバック

9. 今後の拡張計画