複数の専門エージェントを一人で束ねる — Antigravity マルチエージェント・オーケストレーションの実務設計

# Antigravity Agents Configuration
 
## Project Identity
project_name: "e-commerce-platform"
version: "2.0"
language: "en"
 
## Global Instructions
Keep all outputs modular, testable, and production-ready.
Prefer clear function/method names over comments.
Always consider security implications.
 
## Agent Definitions
 
### Manager Agent
name: "orchestrator"
type: "manager"
role: "Coordinates all other agents"
instructions: |
  - Analyze incoming requests
  - Break down complex tasks into sub-tasks
  - Assign tasks to appropriate specialists
  - Validate outputs from sub-agents
  - Merge results into cohesive deliverables
  - Escalate conflicts to human reviewer if needed
 
### Frontend Agent
name: "frontend-specialist"
type: "sub-agent"
role: "React/TypeScript component development"
expertise:
  - React Hooks & State Management
  - TypeScript type definitions
  - Tailwind CSS styling
  - Accessibility (a11y)
instructions: |
  - Follow component composition patterns
  - Implement error boundaries
  - Optimize render performance
  - Use semantic HTML
  - Test with accessibility tools
dependencies: []
output_format: "TypeScript React components"
 
### Backend Agent
name: "backend-specialist"
type: "sub-agent"
role: "Node.js/Express API development"
expertise:
  - RESTful API design
  - Database schema design
  - Authentication & Authorization
  - Input validation & error handling
instructions: |
  - Design APIs that are idempotent
  - Implement proper HTTP status codes
  - Use dependency injection
  - Add comprehensive logging
  - Write defensive code
dependencies: ["database-agent"]
output_format: "Node.js/Express code with TypeScript"
 
### Database Agent
name: "database-specialist"
type: "sub-agent"
role: "Database design and optimization"
expertise:
  - SQL schema design
  - Query optimization
  - Index strategy
  - Data migration
instructions: |
  - Normalize schemas to 3NF minimum
  - Add indexes for query performance
  - Plan for scalability
  - Document migration steps
dependencies: []
output_format: "SQL DDL statements"
 
### QA Agent
name: "qa-specialist"
type: "sub-agent"
role: "Test automation and quality assurance"
expertise:
  - Unit testing (Jest, Vitest)
  - Integration testing
  - E2E testing (Playwright)
  - Coverage analysis
instructions: |
  - Write tests before code (TDD mindset)
  - Aim for >80% code coverage
  - Test error scenarios, not just happy path
  - Use descriptive test names
dependencies: ["frontend-specialist", "backend-specialist"]
output_format: "JavaScript/TypeScript test files"
 
## Execution Strategy
mode: "parallel_with_dependencies"
timeout: 3600
retry_on_failure: true
max_retries: 3

dependencies: ["database-agent"]  # ✅ backend-agent は database schema が必要

output_format: "TypeScript React components (.tsx)"
expected_files:
  - "Button.tsx (with props interface)"
  - "Form.tsx (with validation logic)"

{
  "task": "Build shopping cart feature",
  "sub_tasks": [
    {
      "id": "db-001",
      "agent": "database-specialist",
      "description": "Design shopping cart schema (cart, cart_items tables)",
      "priority": 1
    },
    {
      "id": "api-001",
      "agent": "backend-specialist",
      "description": "Implement POST /api/cart, PUT /api/cart/:id, DELETE /api/cart/:id",
      "priority": 2,
      "depends_on": ["db-001"]
    },
    {
      "id": "ui-001",
      "agent": "frontend-specialist",
      "description": "Build CartPage component with add/remove/checkout flows",
      "priority": 2,
      "depends_on": ["api-001"]
    },
    {
      "id": "payment-001",
      "agent": "backend-specialist",
      "description": "Integrate Stripe payment API",
      "priority": 3,
      "depends_on": ["api-001"]
    },
    {
      "id": "test-001",
      "agent": "qa-specialist",
      "description": "Write tests for cart functionality (unit + integration)",
      "priority": 3,
      "depends_on": ["api-001", "ui-001"]
    }
  ]
}

# schedule.py — depends_on だけを見て実行段（レベル）を求める
from collections import defaultdict
 
def levels(tasks):
    dep = {t["id"]: set(t.get("depends_on", [])) for t in tasks}
    lv, placed, n = {}, set(), 0
    while len(placed) < len(dep):
        ready = [i for i, d in dep.items() if i not in placed and d <= placed]
        if not ready:
            raise SystemExit("循環依存: " + str(set(dep) - placed))
        for i in ready:
            lv[i] = n
        placed |= set(ready)
        n += 1
    return lv, n
 
lv, depth = levels(sub_tasks)
by = defaultdict(list)
for task_id, level in lv.items():
    by[level].append(task_id)
 
print("段数:", depth, "／最大並列幅:", max(len(v) for v in by.values()))
for level in sorted(by):
    print(f"  L{level}: {' '.join(sorted(by[level]))}")

{
  "task_id": "api-001",
  "target_agent": "backend-specialist",
  "context": {
    "project": "e-commerce-platform",
    "tech_stack": ["Node.js", "Express", "TypeScript", "PostgreSQL"],
    "related_schema": {
      "database_schema": "cart table with id, user_id, created_at, updated_at",
      "cart_items": "cart_id, product_id, quantity, price"
    }
  },
  "requirements": [
    "Create POST /api/cart - initialize user cart",
    "Create GET /api/cart/:cartId - fetch cart with items",
    "Create PUT /api/cart/:cartId/items - add/update items",
    "Create DELETE /api/cart/:cartId/items/:itemId - remove item",
    "Implement input validation using Zod",
    "Add error handling (404, 400, 500)",
    "Include TypeScript types for request/response"
  ],
  "output_requirements": {
    "format": "TypeScript Express routes",
    "file_name": "cart.controller.ts",
    "includes_tests": false,
    "doc_required": true
  },
  "constraints": {
    "max_file_size": "500 lines",
    "performance_target": "response < 200ms",
    "security": "Validate user ownership of cart"
  }
}

// orchestrator.js — 素直に書いた版（このあと直します）
async function aggregateResults(subAgentOutputs) {
  const validatedOutputs = {};
 
  for (const [agentName, output] of Object.entries(subAgentOutputs)) {
    if (!validateFormat(output)) {
      throw new Error(`${agentName}: Invalid output format`);   // ここで反復が止まる
    }
 
    if (output.includes('ERROR:') || output.includes('TODO:')) {
      console.warn(`${agentName}: Incomplete output detected`); // 警告を出すだけ
    }
 
    validatedOutputs[agentName] = {
      content: output,
      timestamp: new Date(),
      validated: true                                           // それでも true が付く
    };
  }
 
  return mergeIntoProjectStructure(validatedOutputs);
}

const INCOMPLETE_MARKERS = [/^\s*ERROR:/m, /\bTODO:/, /\bFIXME:/, /<{7} /];
 
function inspect(agentName, output) {
  if (typeof output !== 'string' || output.trim() === '') {
    return { agent: agentName, status: 'invalid', reason: '出力が文字列ではないか空です' };
  }
 
  const hit = INCOMPLETE_MARKERS.find((re) => re.test(output));
  if (hit) {
    return { agent: agentName, status: 'incomplete', reason: `未完成マーカー ${hit} を検出しました` };
  }
 
  return { agent: agentName, status: 'ok', content: output };
}
 
function aggregateResults(subAgentOutputs) {
  const reports = Object.entries(subAgentOutputs).map(([name, out]) => inspect(name, out));
  const accepted = reports.filter((r) => r.status === 'ok');
  const rejected = reports.filter((r) => r.status !== 'ok');
 
  return {
    ok: rejected.length === 0,
    accepted: Object.fromEntries(accepted.map((r) => [r.agent, r.content])),
    rejected
  };
}

# GitHub PR Auto-Review System
 
## Manager Agent
name: "pr-orchestrator"
role: "Coordinates all code review checks"
instructions: |
  - Parse GitHub PR diff
  - Extract changed files
  - Assign files to specialist agents
  - Collect all review comments
  - Generate consolidated review
 
## Static Analysis Agent
name: "lint-analyzer"
expertise: ["ESLint", "TypeScript strict mode", "Code complexity"]
instructions: |
  - Check TypeScript strict mode compliance
  - Run ESLint rules (Airbnb style)
  - Detect circular dependencies
  - Report cyclomatic complexity > 10
checks:
  - type_safety
  - naming_conventions
  - code_complexity
 
## Security Agent
name: "security-scanner"
expertise: ["OWASP", "Dependency vulnerabilities", "Secret detection"]
instructions: |
  - Scan for hardcoded secrets (API keys, passwords)
  - Check dependency versions (npm audit)
  - Detect SQL injection patterns
  - Check authentication logic
checks:
  - secrets
  - vulnerabilities
  - injection_patterns
  - auth_logic
 
## Performance Agent
name: "perf-analyzer"
expertise: ["Rendering performance", "Bundle size", "Database queries"]
instructions: |
  - Check React re-render optimization (useMemo, useCallback)
  - Estimate bundle size impact
  - Detect N+1 queries
  - Check asset loading strategy
checks:
  - react_performance
  - bundle_size
  - database_queries
  - asset_loading
 
## Aggregator Agent
name: "review-aggregator"
role: "Compile all findings into one GitHub comment"
dependencies: ["lint-analyzer", "security-scanner", "perf-analyzer"]
instructions: |
  - Consolidate findings from all agents
  - Categorize by severity (🔴 critical, 🟡 warning, 🟢 info)
  - Format as GitHub markdown comment
  - Tag file locations with line numbers

// webhook.js
const express = require('express');
const { OrchestratorManager } = require('./orchestrator');
 
const app = express();
app.post('/webhook/github', express.json(), async (req, res) => {
  const { action, pull_request } = req.body;
 
  if (action !== 'opened' && action !== 'synchronize') {
    return res.sendStatus(200);
  }
 
  const prNumber = pull_request.number;
  const repo = pull_request.base.repo.full_name;
  const diff = await fetchPRDiff(repo, prNumber);
 
  // Manager Agent に委託
  const orchestrator = new OrchestratorManager(diff, repo, prNumber);
  orchestrator.run().then(reviews => {
    postGitHubComment(repo, prNumber, reviews);
  });
 
  res.sendStatus(202); // Accepted, 非同期処理
});

// agents/lint-analyzer.js
class LintAnalyzer extends SubAgent {
  async analyze(diff) {
    const files = this.parseFiles(diff);
    const issues = [];
 
    for (const file of files) {
      if (!file.name.endsWith('.ts') && !file.name.endsWith('.tsx')) {
        continue;
      }
 
      const fileContent = await getFileContent(file.name);
 
      // ESLint スタイルチェック
      const eslintResults = await this.runESLint(fileContent);
      issues.push(...eslintResults.map(r => ({
        type: 'lint',
        file: file.name,
        line: r.line,
        message: r.message,
        severity: r.severity
      })));
 
      // 型安全性チェック
      const typeErrors = await this.checkTypeScript(fileContent);
      issues.push(...typeErrors);
    }
 
    return {
      agent: 'lint-analyzer',
      issues,
      summary: `Found ${issues.length} issues`
    };
  }
}

// agents/security-scanner.js
class SecurityScanner extends SubAgent {
  async analyze(diff) {
    const findings = [];
 
    // Secret 検出
    const secrets = this.detectSecrets(diff);
    if (secrets.length > 0) {
      findings.push({
        type: 'security_critical',
        message: `Hardcoded secret detected: ${secrets[0]}`,
        severity: 'critical'
      });
    }
 
    // 依存関係チェック
    const vulnDeps = await this.auditDependencies();
    findings.push(...vulnDeps.map(v => ({
      type: 'vulnerability',
      message: `${v.package} has known CVE: ${v.cve}`,
      severity: 'high'
    })));
 
    // SQLインジェクションパターン検出
    const sqlInjections = this.detectSQLInjection(diff);
    findings.push(...sqlInjections);
 
    return {
      agent: 'security-scanner',
      findings,
      summary: `${findings.filter(f => f.severity === 'critical').length} critical issues`
    };
  }
}

// agents/review-aggregator.js
class ReviewAggregator extends SubAgent {
  async aggregate(lintResults, securityResults, perfResults) {
    const allFindings = [
      ...lintResults.issues,
      ...securityResults.findings,
      ...perfResults.issues
    ];
 
    // 重要度でソート
    const sorted = allFindings.sort((a, b) => {
      const severityMap = { critical: 3, high: 2, warning: 1, info: 0 };
      return severityMap[b.severity] - severityMap[a.severity];
    });
 
    // GitHub マークダウン形式で生成
    let comment = '## 🤖 Automated Code Review\n\n';
 
    const critical = sorted.filter(f => f.severity === 'critical');
    if (critical.length > 0) {
      comment += `### 🔴 Critical Issues (${critical.length})\n`;
      critical.forEach(issue => {
        comment += `- **${issue.file}:${issue.line}** - ${issue.message}\n`;
      });
      comment += '\n';
    }
 
    // ...他のセクション同様
 
    return comment;
  }
}

// post-to-github.js
async function postGitHubComment(repo, prNumber, reviewComment) {
  const [owner, repoName] = repo.split('/');
 
  const response = await github.rest.issues.createComment({
    owner,
    repo: repoName,
    issue_number: prNumber,
    body: reviewComment
  });
 
  console.log(`Comment posted: ${response.data.html_url}`);
}

{
  "timestamp": "2026-04-07T10:15:30Z",
  "transaction_id": "mgr-001-23049",
  "phase": "task_decomposition",
  "manager_input": "Build shopping cart API",
  "decomposition_result": [
    {
      "task_id": "db-001",
      "agent": "database-specialist",
      "status": "queued"
    },
    {
      "task_id": "api-001",
      "agent": "backend-specialist",
      "status": "queued",
      "depends_on": ["db-001"]
    }
  ],
  "timestamp_end": "2026-04-07T10:15:32Z",
  "duration_ms": 2000
}

# 特定のトランザクションを追跡
cat orchestration.log | jq '.[] | select(.transaction_id == "mgr-001-23049")'
 
# エージェント別実行時間を集計
cat orchestration.log | jq 'group_by(.agent) | map({agent: .[0].agent, avg_time: (map(.duration_ms) | add / length)})'
 
# エラーが発生したタスクを検索
cat orchestration.log | jq '.[] | select(.status == "failed")'

{
  "transaction_id": "mgr-001-23049",
  "task_id": "db-001",
  "agent": "database-specialist",
  "status": "failed",
  "error": {
    "type": "ValidationError",
    "message": "Invalid schema: column 'user_id' missing foreign key",
    "context": {
      "input_requirements": "Generate cart schema with user_id FK",
      "output_received": "CREATE TABLE cart ...",
      "validation_rule": "FK constraints must match entities"
    }
  },
  "retry_count": 1,
  "next_action": "retry with additional context"
}

// cost-manager.js
class CostManager {
  constructor(monthlyBudget = 1000) {
    this.budget = monthlyBudget;
    this.currentSpend = 0;
  }
 
  async executeWithCostControl(agent, task) {
    const estimatedTokens = this.estimateTokens(task);
    const estimatedCost = estimatedTokens * COST_PER_TOKEN;
 
    if (this.currentSpend + estimatedCost > this.budget) {
      await sendAlert(`Budget exceeded: $${estimatedCost} would exceed limit`);
      return null;
    }
 
    const result = await agent.execute(task);
    this.currentSpend += estimatedCost;
 
    return result;
  }
}

// availability-manager.js
const retryConfig = {
  maxRetries: 3,
  baseDelay: 1000, // 1 second
  maxDelay: 30000  // 30 seconds
};
 
async function executeWithRetry(agent, task) {
  let delay = retryConfig.baseDelay;
 
  for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
    try {
      return await agent.execute(task);
    } catch (error) {
      if (attempt === retryConfig.maxRetries) {
        // エスカレーション
        await escalateToHuman(agent, task, error);
        throw error;
      }
 
      await sleep(Math.min(delay, retryConfig.maxDelay));
      delay *= 2; // 指数バックオフ
    }
  }
}