에이전트 설계 · 환경을 설계하라 · 시작을 누르면 음성과 함께 슬라이드가 자동 재생됩니다. Designing agents · Design the environment · Press start and slides advance with narration.
지난 시간, 팔다리를 붙였습니다 — MCP·Hooks·커스텀 도구. 이제 그 팔다리를 쥔 ‘일꾼’을 만듭니다 — 에이전트. 성능은 머리(모델)가 아니라 ‘일하는 환경’이 가릅니다. Last time we attached limbs — MCP, Hooks, custom tools. Now we build the ‘worker’ that wields them — the agent. Performance comes from the workplace, not the brain (model).
As of 2026-06 · 에이전트 정의의 필드·옵션 이름은 버전마다 바뀝니다 — ‘환경을 설계한다’는 원리가 진실. [추론]As of 2026-06 · the field & option names of an agent definition change by version — the principle ‘design the environment’ is the truth. [inference]
부르는 것과 설계하는 것은 다릅니다. 부탁은 매번 다르지만, 설계된 환경은 매번 같습니다.Calling isn't designing. A request differs every time, but a designed environment is the same every time.
막연한 위임(“알아서”)은 매번 다른 결과를 낳습니다 — ‘어떤 도구로, 어떤 지침으로, 어디까지’가 정해져 있지 않기 때문. 결과를 일정하게 만드는 건 더 똑똑한 모델이 아니라 ‘설계된 환경’. [추론]Vague delegation (“just handle it”) yields a different result each time — because which tools, which instructions, and how far were never set. Consistency comes from a designed environment, not a smarter model. [inference]
같은 Claude라도 도구·지침·범위를 바꾸면 다른 일꾼이 됩니다 — 성능은 머리가 아니라 ‘환경 설계’에서 나옵니다.Same Claude, but swap tools·instructions·scope and you get a different worker — performance comes from environment design, not the brain.
[출처: docs.anthropic.com/en/docs/claude-code/sub-agents] (서브)에이전트는 모델 + 사용 도구 + 시스템 지침(역할)의 조합으로 정의된다. 정의 항목·필드는 2026-06 기준 공식 문서로 현행 확인. → ‘부른다’가 아니라 ‘조합으로 설계한다’. (s12에서 붙인 도구가 여기 ‘도구’ 자리.)[source: docs.anthropic.com/en/docs/claude-code/sub-agents] A (sub)agent is defined as a combination of model + tools + system instructions (role). Items & fields per official docs, as of 2026-06. → Don't ‘call’ one — ‘design’ it by combination. (The tools from s12 slot into this ‘tools’ position.)
필드 이름은 대표 예 — 버전마다 다릅니다.Field names are representative — they vary by version.
| 설계 항목Design item | 무엇을 정하나What you set | 왜 중요한가Why it matters |
|---|---|---|
| 역할·설명Role·description | 언제 불리나When it's called | 엉뚱한 데 안 끼어듦Won't butt into the wrong job |
| 지침Instructions | 어떻게 일하나How it works | 매번 같은 기준Same criteria every time |
| 도구 범위Tool scope | 쥐여 줄 도구만Only the tools you grant | 권한·사고 한정Bounds power·blast radius |
| 모델Model | 일의 체급Weight class for the job | 일에 맞는 무게Right weight for the work |
[출처: docs.anthropic.com/en/docs/claude-code/sub-agents] 정의 파일은 (대표적으로) 역할·설명, 시스템 지침, 사용 도구, 모델을 명시한다 — 이 ‘적어 두기’가 곧 환경 설계. 정확한 필드·형식은 2026-06 기준 공식 문서가 진실(필드명은 ‘대표 예’). → 머릿속이 아니라 파일에 적어 매번 같게.[source: docs.anthropic.com/en/docs/claude-code/sub-agents] A definition file (representatively) specifies role·description, system instructions, tools, and model — this ‘writing down’ is environment design. Exact fields/format per official docs, as of 2026-06 (names are ‘representative’). → Put it in a file, not your head, to keep it the same every time.
범위를 좁히는 게 곧 신뢰를 높이는 것.Narrowing the scope is how you raise trust.
[추론] 또렷한 역할 + 최소 도구 + 명확한 기준이 ‘이것저것 다 하는’ 에이전트보다 일관되고 안전 — 범위가 좁을수록 행동이 예측 가능. (s05 ‘명령 대신 설계’·s08 ‘점진적 공개’ 정합.) → 처음부터 좁게. (좋은/나쁜 사례는 예시.)[inference] Sharp role + minimal tools + clear criteria is more consistent and safer than a ‘does-everything’ agent — narrower scope, more predictable behavior. (Aligns with s05 ‘design over command’ · s08 ‘progressive disclosure’.) → Design it narrow from the start. (Good/bad cases are examples.)
[추론] 범위를 좁히면 (a) 선택지가 줄어 행동이 일관 (b) 권한이 작아 사고 범위가 작고 (c) 도구·지침이 컨텍스트를 덜 차지(많이/적게 — 상대, 구체 토큰 수치 단정 금지). (s12 ‘권한을 좁게’·s02 컨텍스트 보호 정합.) → 필요한 만큼만 쥐여 준다.[inference] Narrowing means (a) fewer options → consistent behavior, (b) smaller power → smaller blast radius, (c) tools·instructions take up less context (more/less — relative; no exact token claims). (Aligns with s12 ‘grant power narrowly’ · s02 protect-the-context.) → Hand over exactly as much as is needed.
모델을 바꾸기 전에, 환경을 바꾼다.Change the environment before you change the model.
[추론] 에이전트 행동은 모델 능력보다 ‘주어진 환경’(도구·지침·범위·맥락)에 크게 좌우 — 환경을 바꾸면 같은 모델이 다르게 행동. 결과 개선의 1차 레버는 ‘더 똑똑한 모델’이 아니라 ‘더 나은 환경 설계’. (s03 ‘확률 예측’·s05 ‘설계’ 정합.) → 결과가 나쁘면 모델 탓 전에 환경부터.[inference] An agent's behavior is governed far more by the given environment (tools·instructions·scope·context) than by raw model ability — change the environment, the same model behaves differently. The first lever for better results is a better-designed environment, not a smarter model. (Aligns with s03 ‘probability prediction’ · s05 ‘design’.) → Bad result? Look at the environment before blaming the model.
| 실패 상황Failure | 나쁜 처리Bad handling | 설계된 처리Designed handling |
|---|---|---|
| 도구가 에러 반환Tool returns an error | 무시하고 진행Ignore and march on | 읽고 재시도·경로 변경Read it, retry·reroute |
| 결과가 비었거나 이상Result empty or off | 그럴듯하게 채움Fill it in plausibly | “확인 못함” 반환Return “couldn't confirm” |
| 막혔는데 계속 시도Stuck but keeps trying | 무한 반복Loops forever | 한도에서 멈춰 보고Stop at the limit, report |
[추론] 잘 설계된 에이전트는 실패를 전제로 한다 — 에러를 읽고 대응, 비면 채우지 말고 ‘모름’ 반환(s03 환각 회피), 막히면 멈춰 보고. 에러 처리를 안 하면 ‘성공적으로’ 사고를 낸다. (s03 환각·s11 ‘결과를 다시 읽기’ 정합.) → 잘 되는 길이 아니라 ‘틀리는 길’을 먼저 설계.[inference] A well-designed agent assumes failure — reads errors and responds, returns ‘unknown’ instead of filling blanks (s03 hallucination avoidance), and stops to report when stuck. Skip error handling and it will ‘fail successfully’. (Aligns with s03 hallucination · s11 ‘reread the output’.) → Design the failure path first, not just the happy path.
멈춤은 실패가 아니라 ‘설계된 안전장치’.Stopping isn't failure — it's a designed safeguard.
[추론] 멈춤 조건을 설계에 넣으면 폭주하지 않는다 — 가정이 깨졌거나, 범위 밖이거나, 같은 시도를 반복하거나, 사람 판단이 필요할 때 멈춰 보고. 멈춤은 실패가 아니라 설계된 안전장치. (s10 ‘중간 검증 포인트’·s12 ‘PreToolUse 가드’ 정합.) → ‘언제 멈출지’를 시작할 때 적어 둔다.[inference] Build stop conditions into the design and it won't run rogue — it stops and reports when an assumption breaks, it's out of scope, it repeats the same attempt, or a human call is needed. Stopping isn't failure — it's a designed safeguard. (Aligns with s10 ‘mid-task checkpoints’ · s12 ‘PreToolUse guard’.) → Write down ‘when to stop’ up front.
| 테스트 항목Test item | 확인 방법How to check |
|---|---|
| 일관성Consistency | 같은 입력 → 매번 비슷한 결과인가Same input → similar result every time? |
| 범위 준수Scope adherence | 범위 밖 일을 거부·멈추나Does it refuse·stop on out-of-scope work? |
| 실패 대응Failure handling | 일부러 에러를 줘도 채우지 않고 보고하나Given an error on purpose, does it report instead of filling in? |
한 번 잘 됐다고 믿지 말고, 여러 번·경계에서.Don't trust one success — test many times, at the edges.
[추론] 한 번 성공으로 신뢰 말고 (a) 같은 일을 여러 번 — ‘일관성’ (b) 범위 밖 일을 줘 — ‘범위 준수’ (c) 일부러 에러를 줘 — ‘실패 대응’을 본다. 경계에서 확인해야 설계가 검증된다. (s03 ‘검증 가능성’·s11 ‘결과를 다시 읽기’ 정합.) → 신뢰는 테스트로 얻는다, 기대로 얻지 않는다.[inference] Don't trust one success — check (a) ‘consistency’ by running the same task many times, (b) ‘scope adherence’ by giving out-of-scope work, (c) ‘failure handling’ by injecting an error. The design is verified only at the edges. (Aligns with s03 ‘verifiability’ · s11 ‘reread the output’.) → Trust is earned by testing, not by expectation.
[추론] 5항목은 슬라이드 05·06·09·08·10과 하나씩 짝 — 역할·도구·중단·에러·테스트. 에이전트는 ‘부르면 끝’이 아니라 ‘환경을 적어 내보내는 것’. → 설계 절반, 테스트 절반. (s11 ‘결과를 다시 읽기’ 정합.)[inference] The five map one-by-one onto slides 05·06·09·08·10 — role·tools·stop·error·test. An agent isn't ‘done when called’ — you deploy it by writing the environment. → Half design, half testing. (Aligns with s11 ‘reread the output’.)
[추론] Rule No.5(명령 대신 설계)·No.11(도구를 써라)·No.12(권한은 좁게)·No.13(환경을 설계하라)이 만나는 지점 — 환경을 설계하면, 매번 부탁하지 않아도 같은 결과. → 환경을 설계할 줄 알면, 무엇을 주고 무엇을 막을지 자동으로 보인다.[inference] Where Rule No.5 (design over command) · No.11 (use tools) · No.12 (grant power narrowly) · No.13 (design the environment) meet — design the environment and the same result comes out without asking every time. → Once you can design environments, what to grant and what to block become obvious.
[추론] 결과의 일관성은 모델이 아니라 환경 설계에서 온다 — ‘매번 부탁’은 매번 다른 결과를, ‘설계된 환경’은 매번 같은 결과를. 부탁은 휘발하고, 설계는 남는다. → 이게 Rule No.13의 핵심.[inference] Consistency comes from environment design, not the model — ‘asking every time’ yields a different result, ‘a designed environment’ the same one. A request evaporates; a design stays. → That's the core of Rule No.13.
한 단어로: 역할 → 도구 → 멈춤·실패 → 테스트.In one phrase: role → tools → stops·failures → test.
다음 강 예고 — 하나를 잘 설계했으니, 이제 여럿을 ‘팀’으로. 멀티에이전트 & 하네스.Next up — you designed one well; now make many into a ‘team’. Multi-agents & the harness.
As of 2026-06 · 정의 필드·옵션은 바뀌어도 ‘역할은 좁게, 도구는 최소로, 멈춤·실패는 미리, 그리고 테스트’라는 원리는 그대로 갑니다. [추론]As of 2026-06 · the definition fields & options will change, but the principle — narrow the role, minimize the tools, pre-plan stops & failures, then test — stays the same. [inference]