최소 권한 원칙
각 에이전트에는 역할에 필요한 도구만 제공합니다
최소 권한 원칙은(는) CoddyKit의 무료 Claude Architect 강의입니다. 이것은 4개 중 4번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 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_toolsperAgentDefinition; the coordinator must includeTaskto 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-toolsfrontmatter, and inject secrets through env vars — never commit tokens.
자주 묻는 질문
“최소 권한 원칙” 강의는 무료인가요?
네 — “최소 권한 원칙” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 Claude Architect 강의 전체를 잠금 해제할 수 있습니다. Claude Architect 강의에는 총 4개의 강의가 포함되어 있습니다.
“최소 권한 원칙”에서 뭘 배우나요?
각 에이전트에는 역할에 필요한 도구만 제공합니다 브라우저에서 직접 실행하는 실습 코드로 Claude Architect을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.
Claude Architect을(를) 시작하는 데 경험이 필요한가요?
사전 경험은 필요하지 않습니다. CoddyKit의 Claude Architect은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 4번째 강의입니다.
“최소 권한 원칙” 강의는 얼마나 걸리나요?
대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.
이 Claude Architect 강의에서 코드를 작성하고 실행할 수 있나요?
네. 모든 Claude Architect 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.