Skip to content

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

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 テンプレート自動適用エンジニア着手時
並行開発管理multiAgentManageRuleworktree 自動作成複数 Issue 同時着手時
ドキュメント生成create-docsdocs/ 配下に自動配置設計 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_urlGitLab リポジトリ URL
{project_id}GitLab API: project.idGitLab 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. 今後の拡張計画 ​

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