Claude Architect · レッスン

最小権限の原則

各エージェントには、その役割に必要なツールだけを与えます

「最小権限の原則」はCoddyKit上の無料Claude Architectレッスンです。これはレッスン4/4です。下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。これはClaude Architect学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Claude Architectコースには全4レッスンが含まれています。

このレッスンの一部はまだ翻訳されておらず、英語で表示されています。

Why Least Privilege?

The Principle of Least Privilege says: give each agent only the tools its role actually needs — nothing more.

In a multi-agent system, the coordinator decomposes work and delegates to specialist subagents. Each subagent should receive a tightly scoped toolset. A research subagent does not need a refund tool. A read-only reviewer does not need Write or Bash.

This is not just security hygiene. Scoped tools also make Claude select the right tool more reliably, which directly improves accuracy on the exam scenarios.

More Tools = Worse Selection

Tool selection is driven by the model reading tool descriptions. The more tools you pile onto one agent, the harder that choice becomes.

4-5 tools per agent is the sweet spot for reliable selection.
At 18+ tools, selection reliability degrades noticeably.
Overlapping or ambiguous descriptions cause misrouting to the wrong tool.

Least privilege and good accuracy point the same direction: keep each agent's toolset small and role-specific.

allowed_tools per Agent

In the Agent SDK, you scope a subagent with an AgentDefinition. Its fields are name, description, system_prompt, and allowed_tools.

The allowed_tools list is exactly where least privilege lives — it is the allowlist of tools that subagent may call. Give a researcher search and read tools only; never hand it write or refund actions.

research_agent = AgentDefinition(
    name="researcher",
    description="Gathers and summarizes external sources with citations.",
    system_prompt="Find sources, extract facts, keep claim->source mappings.",
    allowed_tools=["WebSearch", "WebFetch", "Read"],  # read-only, no Write/Bash
)

The Coordinator Needs Task

Least privilege is about giving the right minimum — not crippling the agent.

The coordinator in a hub-and-spoke system must be able to delegate, so its allowedTools has to include "Task". Without it, the coordinator cannot spawn subagents at all.

So: the coordinator gets Task plus only what it needs to aggregate and route. Each spoke gets just its job-specific tools.

coordinator = AgentDefinition(
    name="coordinator",
    description="Decomposes the request, delegates, aggregates, routes.",
    system_prompt="Break the task into subtasks and dispatch to specialists.",
    allowed_tools=["Task"],  # delegation is its whole job
)

Read-Only vs Write Agents

A common split is read-only investigators versus write-capable executors.

Claude Code's built-in tools make this concrete:

Read-only: Glob (find files by pattern), Grep (search contents), Read (load a file).
Mutating: Write (create), Edit (precise change), Bash (shell).

A code-review agent that only inspects code should get the read-only set. Withholding Write, Edit, and Bash means it physically cannot change the repo, even if a prompt is misread.

reviewer = AgentDefinition(
    name="reviewer",
    description="Reviews a diff for bugs. Never edits files.",
    system_prompt="Inspect code and report issues only.",
    allowed_tools=["Glob", "Grep", "Read"],  # no Write/Edit/Bash
)

Scope by Role, Not Convenience

It is tempting to give every agent the full toolbox "just in case." Resist it.

The fact sheet is blunt: scope tools to the role. Each agent's tools should map to its responsibilities, not to whatever might be handy.

Two reasons:

Safety — an agent cannot misuse a tool it was never given.
Reliability — fewer, role-relevant tools mean clearer, non-overlapping descriptions and better selection.

Privilege Boundaries Still Need Hooks

Least privilege limits which tools exist for an agent. But for a critical business rule inside an allowed tool, an allowlist is not enough.

Example: the support agent legitimately has process_refund, but refunds over $500 must be blocked. A prompt enforces a rule only ~90% of the time. A hook enforces it 100% deterministically.

Use an outgoing-call hook to block policy-violating actions when failure has financial, legal, or safety consequences.

# Pseudocode: deterministic guardrail on an allowed tool
def on_tool_call(tool_name, args):
    if tool_name == "process_refund" and args["amount"] > 500:
        return Block(reason="Refund over $500 requires human approval")
    return Allow()

Preconditions: Earn the Privilege

Least privilege also applies in time: an agent should not exercise a sensitive tool until preconditions are met.

In the customer support scenario, process_refund must not run until get_customer has returned a verified customer ID. A programmatic precondition gives a deterministic guarantee that prompt guidance alone cannot.

So privilege is conditional: the tool is in the allowlist, but a hook or precondition gates when it may fire.

def on_tool_call(tool_name, args, state):
    if tool_name == "process_refund" and not state.verified_customer_id:
        return Block(reason="Verify identity via get_customer first")
    return Allow()

Skills and Commands: allowed-tools

Least privilege is not only an SDK concept — Claude Code Skills support it too.

A skill's frontmatter can set allowed-tools to restrict what that skill may invoke, plus context: fork to isolate verbose output and argument-hint for inputs.

A skill that only formats text should not be allowed to run Bash. Restricting it in frontmatter keeps the privilege boundary close to the capability.

---
name: summarize-diff
description: Summarize a git diff in plain language.
allowed-tools: [Read, Grep]
context: fork
argument-hint: <path-to-diff>
---
Read the diff and produce a concise summary. Do not modify files.

Secrets Are a Privilege Too

Tools that reach external systems often need credentials — and credentials are privilege.

For MCP servers, inject secrets via environment variables like ${GITHUB_TOKEN}, and never commit tokens. Use .mcp.json at project scope (shared in VCS) for the server config, but keep the actual secret out of the file.

This keeps the token scoped to the environment that genuinely needs it, instead of leaking it into source control where every agent and teammate inherits it.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

Putting It Together

A well-scoped hub-and-spoke system layers least privilege cleanly:

Coordinator: Task + routing tools, nothing destructive.
Researcher: WebSearch, WebFetch, Read — read-only.
Reviewer: Glob, Grep, Read — no writes.
Executor: Edit, Write, Bash — and its risky calls are gated by hooks/preconditions.

Every agent stays near the 4-5 tool sweet spot, descriptions stay crisp, and the dangerous capabilities are both scoped and deterministically guarded.

Quick Check

Apply least privilege to a multi-agent design decision.

Recap

Key takeaways for least-privilege agent design:

Give each agent only the tools its role needs — scope by role, not convenience.
Aim for 4-5 tools per agent; selection degrades at 18+.
Set allowed_tools per AgentDefinition; the coordinator must include Task to delegate.
Split read-only (Glob/Grep/Read) from write-capable (Write/Edit/Bash) agents.
For critical rules inside an allowed tool, enforce with hooks and preconditions (100% deterministic), not prompts (~90%).
Restrict skills via allowed-tools frontmatter, and inject secrets through env vars — never commit tokens.

よくある質問

「最小権限の原則」レッスンは無料ですか？

はい。「最小権限の原則」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Claude Architectコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Claude Architectコースには全4レッスンが含まれています。

「最小権限の原則」で何を学びますか？

各エージェントには、その役割に必要なツールだけを与えますブラウザで直接実行するハンズオンコードでClaude Architectを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

Claude Architectを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのClaude Architectは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。これはレッスン4/4です。

「最小権限の原則」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このClaude Architectレッスンでコードを書いて実行できますか？

はい。すべてのClaude Architectレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

← Claude Architectに戻る