10日で覚えるKiro CLIDay 5: カスタムエージェント実践
第 510日で覚えるKiro CLI

toolsSettings によるツール設定

Day 4 では tools と allowedTools でツールのアクセスを制御しました。toolsSettings を使うと、各ツールの動作をさらに細かく制御できます。

shell ツールの制御

{
  "toolsSettings": {
    "shell": {
      "allowedCommands": ["npm test", "npm run build", "git diff", "git log"],
      "deniedCommands": ["rm -rf", "sudo", "chmod 777"],
      "denyByDefault": true,
      "autoAllowReadonly": true
    }
  }
}
設定 説明
allowedCommands 確認なしで実行を許可するコマンド（正規表現対応）
deniedCommands 実行をブロックするコマンド
denyByDefault デフォルトで全コマンドをブロック
autoAllowReadonly 読み取り専用コマンドを自動許可

aws ツールの制御

{
  "toolsSettings": {
    "aws": {
      "allowedServices": ["s3", "lambda", "cloudformation", "logs"],
      "deniedServices": ["iam", "organizations"],
      "autoAllowReadonly": true
    }
  }
}

read / write ツールの制御

{
  "toolsSettings": {
    "read": {
      "allowedPaths": ["src/**", "tests/**", "docs/**", "*.md"],
      "deniedPaths": [".env", "*.key", "secrets/**"]
    },
    "write": {
      "allowedPaths": ["src/**", "tests/**"],
      "deniedPaths": ["package-lock.json", "node_modules/**"]
    }
  }
}

web_fetch ツールの制御

{
  "toolsSettings": {
    "web_fetch": {
      "trusted": ["https://docs\\..*", "https://api\\.github\\.com/.*"],
      "blocked": ["https://internal\\.company\\.com/.*"]
    }
  }
}

toolAliases — ツール名の衝突解決

複数の MCP サーバーが同じ名前のツールを提供する場合、toolAliases でリネームできます。

{
  "toolAliases": {
    "@github-mcp/get_issues": "github_issues",
    "@jira-mcp/get_issues": "jira_issues"
  }
}

これにより、プロンプト内で github_issues と jira_issues を明確に区別して使用できます。

resources — コンテキストの自動ロード

resources フィールドで、エージェント起動時に自動的にロードするファイルを指定します。

file:// リソース

起動時にファイル内容が直接コンテキストにロードされます。

{
  "resources": [
    "file://README.md",
    "file://.kiro/steering/**/*.md",
    "file://CONTRIBUTING.md"
  ]
}

グロブパターンで複数ファイルをまとめて指定できます。

skill:// リソース

起動時にメタデータのみロードし、必要に応じて全内容をロードします。大きなドキュメントに適しています。

{
  "resources": [
    "skill://.kiro/skills/**/SKILL.md"
  ]
}

ナレッジベース

大量のドキュメントはナレッジベースとして登録し、検索時のみコンテキストを消費します。

{
  "resources": [
    {
      "type": "knowledgeBase",
      "source": "./docs",
      "name": "project-docs",
      "description": "Project documentation and API references",
      "indexType": "best",
      "autoUpdate": true
    }
  ]
}
インデックスタイプ 特徴 用途
fast BM25語彙検索、高速 ログ、設定ファイル、大規模コードベース
best セマンティック検索、高精度 ドキュメント、リサーチ資料

実践的なエージェント例

AWS スペシャリスト

{
  "name": "aws-specialist",
  "description": "AWS infrastructure and development tasks",
  "prompt": "You are an AWS infrastructure expert. Follow AWS Well-Architected Framework best practices.",
  "tools": ["read", "write", "shell", "aws"],
  "allowedTools": ["read", "aws"],
  "toolsSettings": {
    "aws": {
      "allowedServices": ["s3", "lambda", "cloudformation", "ec2", "iam", "logs"],
      "autoAllowReadonly": true
    },
    "write": {
      "allowedPaths": ["infrastructure/**", "scripts/**", "*.yaml", "*.yml", "*.json"]
    }
  },
  "model": "claude-sonnet-4"
}

用途: CloudFormation スタックのデプロイ、S3/Lambda 管理、インフラのトラブルシューティング。

開発ワークフロー（Git MCP 連携）

{
  "name": "dev-workflow",
  "description": "Development workflow with Git integration",
  "mcpServers": {
    "git": {
      "command": "git-mcp-server",
      "args": []
    }
  },
  "tools": ["read", "write", "shell", "@git"],
  "allowedTools": [
    "read",
    "@git/git_status",
    "@git/git_log",
    "@git/git_diff"
  ],
  "toolsSettings": {
    "write": {
      "allowedPaths": ["src/**", "tests/**", "docs/**", "*.md", "*.json"]
    }
  }
}

用途: コードレビュー、テスト作成、Git ワークフロー管理、ドキュメント更新。

コードレビュー専用

{
  "name": "code-reviewer",
  "description": "Code review and quality analysis (read-only)",
  "prompt": "You are a senior code reviewer. Focus on code quality, security vulnerabilities, adherence to coding standards, and potential improvements.",
  "tools": ["read", "shell"],
  "allowedTools": ["read"],
  "toolsSettings": {
    "shell": {
      "allowedCommands": [
        "grep", "find", "wc", "head", "tail", "cat", "diff",
        "git diff", "git log", "eslint", "pylint"
      ]
    }
  },
  "resources": [
    "file://CONTRIBUTING.md",
    "file://.kiro/steering/**/*.md"
  ]
}

用途: プルリクエストのレビュー、セキュリティ脆弱性の検出、コーディング規約のチェック。write ツールを含まないため、コードを変更するリスクがありません。

プロジェクト固有（Docker + DB 連携）

{
  "name": "backend-dev",
  "description": "Backend development with Docker and PostgreSQL",
  "mcpServers": {
    "docker": {
      "command": "docker-mcp-server",
      "args": []
    },
    "database": {
      "command": "postgres-mcp-server",
      "args": [],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  },
  "tools": ["read", "write", "shell", "@docker", "@database"],
  "allowedTools": [
    "read",
    "@docker/docker_ps",
    "@docker/docker_logs",
    "@database/query_read_only"
  ],
  "toolsSettings": {
    "write": {
      "allowedPaths": [
        "src/**", "tests/**", "migrations/**",
        "docker-compose.yml", "Dockerfile", "requirements.txt"
      ]
    },
    "shell": {
      "allowedCommands": [
        "npm test", "npm run build",
        "docker-compose up", "docker-compose down", "docker-compose logs"
      ]
    }
  }
}

用途: Docker コンテナ管理、データベースクエリ、マイグレーション、API テスト。

flowchart TB
    subgraph AWS["AWS Specialist"]
        A1["read, write, shell, aws"]
        A2["S3, Lambda, CF, EC2"]
    end
    subgraph Dev["Dev Workflow"]
        D1["read, write, shell, @git"]
        D2["status, log, diff"]
    end
    subgraph Review["Code Reviewer"]
        R1["read, shell のみ"]
        R2["grep, diff, lint"]
    end
    subgraph Backend["Backend Dev"]
        B1["read, write, shell, @docker, @db"]
        B2["docker_ps, query_read_only"]
    end
    style AWS fill:#f59e0b,color:#fff
    style Dev fill:#3b82f6,color:#fff
    style Review fill:#22c55e,color:#fff
    style Backend fill:#8b5cf6,color:#fff

MCP サーバーの設定

エージェント設定内で MCP サーバーを直接定義できます。

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/mcp-server"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      },
      "timeout": 120000
    }
  },
  "includeMcpJson": true
}
フィールド 説明
command 実行するコマンド（必須）
args コマンドの引数
env 環境変数
timeout タイムアウト（ミリ秒、デフォルト 120000）

includeMcpJson を true にすると、ワークスペースとユーザーレベルの MCP 設定（.kiro/settings/mcp.json と ~/.kiro/settings/mcp.json）も自動的に読み込まれます。

HTTP MCP サーバー

リモートサーバーへの接続も可能です。

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp",
      "oauth": {
        "redirectUri": "http://localhost:38951",
        "oauthScopes": ["repo", "user", "read:org"]
      }
    }
  }
}

トラブルシューティング

JSON 構文エラー

> /agent schema

設定ファイルのスキーマを確認し、構文を検証します。よくある間違い：

  • 末尾のカンマ
  • 引用符の不足
  • ブラケットの不一致

エージェントが見つからない

> /agent list
  • ファイルの場所を確認（.kiro/agents/ or ~/.kiro/agents/）
  • ファイル拡張子が .json であることを確認
  • ファイル名とエージェント名の一致を確認

ツールが利用できない

  • tools 配列にツールが含まれているか確認
  • MCP サーバーが正しく設定されているか確認
  • MCP ツールは @server_name/tool_name 形式で指定

権限確認が消えない

  • tools と allowedTools の両方にツールが含まれているか確認
  • スペルの不一致がないか確認
  • MCP ツールはフルプレフィックス形式で allowedTools に追加

まとめ

項目 内容
toolsSettings ツールの動作を細かく制御
toolAliases ツール名の衝突を解決
resources file://, skill://, knowledgeBase で自動コンテキスト
MCP 設定 エージェント内で直接定義、HTTP/OAuth 対応
実践例 AWS、Git連携、コードレビュー、Docker+DB

Day 6 では、コードインテリジェンスによる高度なコード理解を学びます。