교육 영상 · 셀프 재생Learning video · self-running

RULE No.13

에이전트 설계 · 환경을 설계하라 · 시작을 누르면 음성과 함께 슬라이드가 자동 재생됩니다. Designing agents · Design the environment · Press start and slides advance with narration.

1·2 언어 전환 · ← → 수동 이동 · Space 재생/정지1·2 language · ← → navigate · Space play/pause
에이전트 설계 · No.13
01 / 14 목차Index
  이동 · F 전체화면 · RULE №13 · DESIGN THE ENVIRONMENT   navigate · F fullscreen · RULE №13 · DESIGN THE ENVIRONMENT [email protected]
일시정지Paused
0 / 0
Home
교육 세션 · 결과는 환경이 가른다Learning session · the environment decides the result

RULE No.13

환경을
설계하라.
Design the
environment.

지난 시간, 팔다리를 붙였습니다 — 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]

설계 · DESIGNDESIGN
1막 — 같은 일꾼, 다른 결과Act 1 — Same worker, different result

“알아서 잘 해줘” — 왜 매번 다르게 할까?“Just handle it well” — why does it work differently every time?

> 이 일 좀 알아서 잘 해줘

알겠습니다 — 어떤 도구로, 어디까지 할지는…
← 기준 없음

매번 다른 도구로, 매번 다르게 일합니다.
> just handle this however you see fit

Got it — but which tools, and how far…
← no criteria

Different tools, a different way, every time.

부르는 것과 설계하는 것은 다릅니다. 부탁은 매번 다르지만, 설계된 환경은 매번 같습니다.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]

2막 — 에이전트란 무엇인가Act 2 — What an agent is

에이전트는 모델이 아니다 — Claude + 도구 + 지침의 ‘조합’이다.An agent isn't a model — it's Claude + tools + instructions, combined.

ClaudeClaude모델model
+
도구 묶음tool set쥐여 줄 것what you hand it
+
지침 / 역할instructions / role어떻게 일하나how it works
에이전트agent하나의 일꾼one worker

같은 Claude라도 도구·지침·범위를 바꾸면 다른 일꾼이 됩니다 — 성능은 머리가 아니라 ‘환경 설계’에서 나옵니다.Same Claude, but swap tools·instructions·scope and you get a different worker — performance comes from environment design, not the brain.

[출처: code.claude.ai/docs/en/docs/sub-agents] (서브)에이전트는 모델 + 사용 도구 + 시스템 지침(역할)의 조합으로 정의된다. 정의 항목·필드는 2026-06 기준 공식 문서로 현행 확인. → ‘부른다’가 아니라 ‘조합으로 설계한다’. (s12에서 붙인 도구가 여기 ‘도구’ 자리.) 예: ‘재고 조회 도구’만 쥐여 준 도우미와 ‘POS 전체 권한’을 준 도우미는 같은 Claude라도 전혀 다르게 일합니다.[source: code.claude.ai/docs/en/docs/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.) E.g. a helper given only a ‘check-inventory tool’ vs. one given ‘full POS access’ will work in completely different ways — even though it’s the same Claude.

2막 — 무엇을 설계하나Act 2 — What you actually design

에이전트 정의 = 4가지를 적어 두는 것.An agent definition = writing down four things.

필드 이름은 대표 예 — 버전마다 다릅니다.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

[출처: code.claude.ai/docs/en/docs/sub-agents] 정의 파일은 (대표적으로) 역할·설명, 시스템 지침, 사용 도구, 모델을 명시한다 — 이 ‘적어 두기’가 곧 환경 설계. 정확한 필드·형식은 2026-06 기준 공식 문서가 진실(필드명은 ‘대표 예’). → 머릿속이 아니라 파일에 적어 매번 같게.[source: code.claude.ai/docs/en/docs/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.

2막 — 무엇이 좋은 설계인가Act 2 — What makes a good design

좋은 에이전트는 ‘넓게’가 아니라 ‘좁고 또렷하게’.A good agent is narrow and sharp — not broad.

나쁜 정의Bad definition
  • 역할이 막연 (“매장 일 다 도와주는 도우미”)Vague role (“helps with everything in the store”)
  • 모든 도구 다 줌All tools granted
  • 멈춤·반환 기준 없음No criteria to stop·return
→ 매번 다르게→ different every time
좋은 정의Good definition
  • 역할 한 줄로 또렷 (“반품 문의에만 답장 초안 잡는 도우미”)Role sharp in one line (“drafts reply for return inquiries only”)
  • 필요한 도구만Only the tools needed
  • 언제 멈출지·뭘 반환할지 명시When to stop·what to return spelled out
→ 매번 같게→ 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.)

2막 — 범위를 좁히면 생기는 일Act 2 — What narrowing buys you

도구를 ‘다’ 주지 않을수록, 일꾼은 더 똑똑해 보인다.The fewer tools you grant, the smarter the worker looks.

범위가 넓으면Broad scope
헤매고, 위험하다wanders, risky
  • 고를 도구가 많아 헤맴too many tools to pick — it wanders
  • 권한이 커서 사고 범위도 큼big power, big blast radius
  • 지침이 두루뭉술fuzzy instructions
범위가 좁으면Narrow scope
빠르고, 일관된다fast, consistent
  • 고를 게 적어 빠르고 일관few to pick — fast and consistent
  • 권한이 좁아 사고 한계small power, bounded blast radius
  • 역할이 또렷sharp role

[추론] 범위를 좁히면 (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.

3막 — 왜 환경이 결과를 가르나Act 3 — Why the environment decides

같은 Claude도, 환경이 다르면 다르게 행동한다.The same Claude behaves differently in a different environment.

같은
모델
same
model
환경 A — 좁은 도구 · 또렷한 지침Env A — narrow tools · sharp instructions
행동 A: 일관behavior A: consistent
환경 B — 모든 도구 · 막연한 지침Env B — all tools · vague instructions
행동 B: 제멋대로behavior B: erratic

모델을 바꾸기 전에, 환경을 바꾼다.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.

3막 — 일꾼이 넘어질 때Act 3 — When the worker stumbles

에이전트는 ‘실패할 것’을 전제로 설계한다.Design the agent assuming it will fail.

실패 상황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.

3막 — 멈출 줄 아는 일꾼Act 3 — A worker that knows to stop

좋은 에이전트는 ‘끝까지 한다’가 아니라 ‘멈출 때를 안다’.A good agent knows when to stop — not just how to finish.

가정이 틀렸다는 증거 Evidence an assumption was wrong 권한·범위 밖의 일 A job outside its power·scope 같은 시도 반복 (루프) The same attempt repeating (a loop) 사람의 판단이 필요한 분기 A branch that needs human judgment

멈춤은 실패가 아니라 ‘설계된 안전장치’.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.

3막 — 설계가 맞는지 확인Act 3 — Verifying the design

에이전트도 ‘배포 전 테스트’ — 같은 일을 여러 번 시켜 본다.Test an agent before you trust it — run the same task a few times.

테스트 항목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.

4막 — 일꾼을 내보내기 전에Act 4 — Before you deploy the worker

이 5가지로, 일꾼을 ‘설계해서’ 내보낸다.Deploy a well-designed worker with these five.

  1. 1
    역할이 한 줄로 또렷한가?Is the role sharp in one line? → 막연한 ‘다 하는 도우미’ 아님→ not a vague “does-everything helper”
  2. 2
    도구를 필요한 만큼만 쥐여 줬나?Did you grant only the tools needed? → 권한 한정→ bound the power
  3. 3
    언제 멈출지(중단 조건)를 적었나?Did you write when to stop (stop conditions)? → 폭주 방지선→ an anti-runaway line
  4. 4
    실패하면 어떻게(에러 핸들링)를 적었나?Did you write how it fails (error handling)? → 틀리는 길 먼저→ the failure path first
  5. 5
    여러 번·경계에서 테스트했나?Did you test many times, at the edges? → 한 번 성공으로 믿지 않기→ don't trust one success

[추론] 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’.)

4막 — 한 줄로 굳히기Act 4 — Lock it into one line

그래서 — 역할은 좁게, 도구는 최소로, 멈춤·실패는 미리, 그리고 테스트.So — narrow the role, minimize the tools, pre-plan stops & failures, then test.

좋은 에이전트 = [또렷한 역할] + [최소 도구] + [멈출 때] + [실패 대응]
  → 그리고 여러 번 테스트한 뒤 신뢰
A good agent = [sharp role] + [minimal tools] + [when to stop] + [failure handling]
  → then trust, after testing many times

[추론] 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.

4막 — 같은 일꾼, 다른 결과Act 4 — Same worker, different outcome

‘매번 부탁한다’와 ‘환경을 설계한다’는 다르다.‘Asking every time’ and ‘designing the environment’ are different.

설계 없이No design
‘알아서 해줘’를 매번 다시 부탁 — 결과는 매번 다름.Re-ask “just handle it” every time — the result differs every time.
환경을 설계Designed environment
역할·도구·멈춤·실패를 적어 두니 — 매번 같게 일함.Role·tools·stops·failures written down — it works the same every time.

[추론] 결과의 일관성은 모델이 아니라 환경 설계에서 온다 — ‘매번 부탁’은 매번 다른 결과를, ‘설계된 환경’은 매번 같은 결과를. 부탁은 휘발하고, 설계는 남는다. → 이게 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.

닫으며 — 환경을 설계하라Closing — design the environment

일꾼을 바꾸지 말고,
일터를 설계하라.
Don't swap the worker —
design the workplace.

한 단어로: 역할 → 도구 → 멈춤·실패 → 테스트.In one phrase: role → tools → stops·failures → test.

다음 강 예고 — 하나를 잘 설계했으니, 이제 여럿을 ‘팀’으로. 멀티에이전트 & 하네스.Next up — you designed one well; now make many into a ‘team’. Multi-agents & the harness.

RULE No.13

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]

강의 노트Lecture notes

13강 · 에이전트 설계Lesson 13 · Designing Agents

Rule No.13 — 환경을 설계하라Rule No.13 — Design the environment

강의 요약Summary

일꾼에게 "이 일 좀 알아서 잘 해줘"라고 통째로 맡기면, 분명 같은 Claude인데도 어제는 이렇게, 오늘은 저렇게, 결과가 매번 들쭉날쭉합니다. 왜 그럴까요. 어떤 도구를 써야 하는지, 어떤 기준으로 판단해야 하는지, 어디까지 손대도 되는지를 정해 주지 않았기 때문입니다. 일꾼을 부르는 것과, 일꾼을 설계하는 것은 완전히 다른 일입니다. 부탁은 할 때마다 말이 조금씩 달라지지만, 한 번 설계해서 적어 둔 환경은 매번 같게 작동합니다.When you hand a whole job to a worker — "just handle this however you see fit" — the results come out all over the place: one way yesterday, another way today, even though it's clearly the same Claude. Why? Because you never specified which tools to use, what criteria to judge by, or how far it's allowed to reach. Calling a worker and designing one are entirely different things. A request shifts a little in wording every time, so the result shifts too. But an environment you design and write down once works the same every time.

이 강의의 핵심은 에이전트의 정체를 다시 보는 데서 출발합니다. 많은 분들이 에이전트를 더 똑똑한 모델 정도로 오해하지만, 그렇지 않습니다. 에이전트는 세 가지의 조합입니다 — Claude(모델), 쥐여 줄 도구 묶음, 그리고 어떻게 일할지를 적은 지침과 역할. 같은 Claude라도 도구를 바꾸고, 지침을 바꾸고, 범위를 바꾸면 완전히 다른 일꾼이 됩니다. 머리는 그대로인데 일하는 모습이 달라지는 겁니다. 그러니까 성능은 머리에서 나오는 게 아니라 환경 설계에서 나옵니다. 결과가 나쁘게 나오면, 모델 탓을 하기 전에 환경부터 보세요. 모델을 바꾸기 전에 환경을 바꾼다 — 이것이 Rule No.13의 의미입니다.The heart of this lecture begins by re-examining what an agent actually is. Many people mistake an agent for some kind of smarter model. It isn't. An agent is a combination of three things — Claude (the model), the set of tools you hand it, and the instructions and role that say how it should work. Take the same Claude, swap the tools, swap the instructions, swap the scope, and you get a completely different worker. The brain is unchanged, but how it works is transformed. So performance doesn't come from the brain; it comes from environment design. When a result comes out badly, look at the environment before you blame the model. Change the environment before you change the model — that is the meaning of Rule No.13.

그렇다면 환경을 어떻게 설계할까요. 첫째, 역할을 좁고 또렷하게 정합니다. "이것저것 다 하는 도우미"가 아니라 한 문장으로 설명되는 역할이어야 합니다. 둘째, 도구는 최소로 줍니다. 많이 줘야 똑똑해진다고 생각하기 쉽지만 오히려 반대입니다 — 범위가 좁을수록 행동이 예측 가능하고, 그래서 더 안전하고 일관됩니다. 셋째, 실패와 멈춤을 미리 설계합니다. 일꾼은 반드시 넘어지므로, 잘 될 거라고 가정하지 말고 실패할 거라고 가정합니다. 도구가 에러를 내면, 결과가 비면, 막히면 어떻게 할지를 먼저 적어 둡니다. 에러 처리를 안 해 두면 에이전트는 멈추지 않고 끝까지 가서 틀린 것을 그럴듯하게 완성해 버립니다 — 성공적으로 사고를 내는 셈입니다. 넷째, 배포 전에 테스트합니다. 한 번 잘 됐다고 믿지 말고, 같은 일을 여러 번, 그리고 경계에서 시켜 보세요. 신뢰는 기대로 얻는 게 아니라 테스트로 얻습니다. 정의 파일의 필드 이름이나 옵션은 버전마다 바뀌지만, 역할은 좁게·도구는 최소로·멈춤과 실패는 미리·그리고 테스트라는 원리는 그대로 갑니다.So how do you design the environment? First, make the role narrow and sharp. Not a "does-everything helper," but a role you can describe in a single sentence. Second, grant tools minimally. It's tempting to think more tools make it smarter, but it's the opposite — the narrower the scope, the more predictable the behavior, and therefore the safer and more consistent. Third, design for failure and stopping in advance. A worker will absolutely stumble, so don't assume it'll go fine — assume it'll fail. Write down ahead of time what to do when a tool errors, when a result is empty, when it gets stuck. If you don't handle errors, the agent won't stop — it'll run all the way to the end and finish something wrong, plausibly; it fails successfully. Fourth, test before you deploy. Don't trust one success — run the same task many times, and at the edges. Trust isn't earned by expectation; it's earned by testing. The field names and options in a definition file change from version to version, but the principle — narrow the role, minimize the tools, pre-plan stops and failures, then test — stays the same.

핵심 개념 5가지Five key concepts

  1. 01

    에이전트 = Claude + 도구 + 지침의 조합An agent = Claude + tools + instructions

    에이전트는 더 똑똑한 모델이 아니라 세 가지의 조합입니다 — Claude(모델), 쥐여 줄 도구 묶음, 그리고 어떻게 일할지를 적은 지침과 역할. 공식 문서도 서브에이전트를 이렇게 모델·사용할 도구·시스템 지침의 조합으로 정의합니다. 같은 Claude라도 도구·지침·범위를 바꾸면 완전히 다른 일꾼이 됩니다. 그래서 성능은 머리가 아니라 환경 설계에서 나옵니다.An agent isn't a smarter model — it's a combination of three things: Claude (the model), the set of tools you hand it, and the instructions and role that say how it should work. The official docs define a subagent exactly this way: a combination of a model, the tools it can use, and a system instruction. Take the same Claude and swap the tools, instructions, or scope, and you get a completely different worker. That's why performance comes from environment design, not the brain.

  2. 02

    역할은 좁고 또렷하게Make the role narrow and sharp

    에이전트를 설계한다는 건 대표적으로 네 가지를 적어 두는 일입니다 — 역할·설명(언제 불리나), 지침(어떻게 일하나), 도구 범위(쥐여 줄 도구만), 모델(일의 체급). 나쁜 정의는 역할이 막연하고("다 하는 도우미") 모든 도구를 다 주며 기준이 없어 매번 다르게 일합니다. 좋은 정의는 역할이 한 줄로 또렷하고, 필요한 도구만 주고, 언제 멈출지·무엇을 반환할지가 명시돼 매번 같게 일합니다.Designing an agent means, representatively, writing down four things: role and description (when it gets called), instructions (how it works), tool scope (only the tools you grant), and model (the weight class for the job). A bad definition has a vague role ("does-everything helper"), grants every tool, and has no criteria — so it works differently every time. A good definition has a role sharp in one line, grants only the tools needed, and spells out when to stop and what to return — so it works the same every time.

  3. 03

    도구는 최소로Minimize the tools

    도구를 많이 줘야 똑똑해진다고 생각하기 쉽지만 오히려 반대입니다. 범위가 넓으면 고를 도구가 많아 헤매고, 권한이 커서 사고 범위도 크고, 지침이 두루뭉술해집니다. 좁히면 고를 게 적어 빠르고 일관되며, 권한이 좁아 사고가 나도 범위가 작고, 역할이 또렷해집니다. 게다가 도구·지침이 많을수록 정의 자체가 컨텍스트를 더 차지하므로, 딱 필요한 만큼만 쥐여 주는 것이 가볍고 안전합니다.It's tempting to think more tools make it smarter, but it's the opposite. With a broad scope there are too many tools to pick, so it wanders; the power is big, so the blast radius is big; and the instructions turn fuzzy. Narrow it, and there's little to pick — fast and consistent; the power is small, so a mishap stays small; and the role is sharp. On top of that, the more tools and instructions there are, the more the definition itself takes up context — so handing over exactly as much as is needed is lighter and safer.

  4. 04

    실패와 멈춤을 전제로 설계Design for failure and stopping

    일꾼은 반드시 넘어집니다. 그래서 잘 설계된 에이전트는 잘 될 거라고 가정하지 않고 실패할 거라고 가정합니다 — 도구가 에러를 내면 읽고 재시도·우회하고, 결과가 비면 그럴듯하게 채우지 말고 "확인 못함"을 반환하며, 막히면 무한 반복 대신 한도에서 멈춰 보고합니다. 멈춤은 실패가 아니라 설계된 안전장치입니다. 가정이 깨졌거나, 범위 밖이거나, 같은 시도를 반복하거나, 사람 판단이 필요할 때 멈추도록 미리 적어 두면 에이전트가 폭주하지 않습니다.A worker will absolutely stumble. So a well-designed agent doesn't assume it'll go fine — it assumes it'll fail: when a tool errors, read it and retry or reroute; when a result is empty, return "couldn't confirm" instead of filling it in plausibly; when stuck, stop at a preset limit and report rather than looping forever. Stopping isn't failure — it's a designed safeguard. If you write down in advance to stop when an assumption breaks, when something is out of scope, when the same attempt repeats, or when a fork needs human judgment, the agent won't go rogue.

  5. 05

    배포 전 테스트 — 같은 일을 여러 번Test before you deploy

    설계를 마쳤다고 바로 믿고 쓰면 안 됩니다. 신입에게 일을 맡기기 전에 몇 번 시켜 보듯, 에이전트도 배포 전에 테스트합니다 — 같은 입력에 매번 비슷한 결과가 나오는지(일관성), 범위 밖 일을 거부·멈추는지(범위 준수), 일부러 에러를 줘도 채우지 않고 보고하는지(실패 대응). 한 번 성공은 운일 수 있으니, 여러 번 그리고 경계에서 시켜 봐야 설계가 검증됩니다. 신뢰는 기대로 얻는 게 아니라 테스트로 얻습니다.Finishing the design doesn't mean you can just trust it. Like giving a new hire a task a few times before handing them the real thing, you test an agent before deploying it: does the same input give a similar result every time (consistency); does it refuse or stop on out-of-scope work (scope adherence); does it report honestly instead of filling in the blank when given an error on purpose (failure handling). One success might just be luck, so you only verify the design by running it many times and at the edges. Trust isn't earned by expectation — it's earned by testing.

실습 예제Exercise

좁은 역할의 도우미를 직접 하나 설계해 봅니다. 코드도, 설정 파일도 필요 없습니다 — Claude 대화창에 아래 지시문을 그대로 붙여 넣어 "고객 문의 답장 초안 도우미"를 만든 다음, 같은 일을 여러 번·까다로운 입력으로 시켜 보며 역할·자료·멈춤·실패가 글로 못 박혔는지 확인하는 연습입니다. 반품·교환·배송지연 같은 CS 문의에 답장 초안을 잡아 주는, 매장운영·CS 실무에서 매일 마주치는 일이 소재입니다. 네 가지만 또렷하면 어떤 업무 도우미든 같은 방식으로 설계할 수 있습니다 — ① 역할 한 줄(좁게) ② 쓸 자료만 한정 ③ 멈출 때 규칙 ④ 실패 시 행동.Design one narrow-role helper yourself. No code, no config files — you just paste the instruction below straight into a Claude chat to create a "customer-inquiry reply-draft assistant," then run the same task several times and on tricky inputs to check whether the role, materials, stops, and failures are nailed down in writing. The subject is something CS and store-operations staff face every day: drafting replies to inquiries about returns, exchanges, and delivery delays. Once these four are sharp, you can design any work helper the same way: (1) a one-line role (narrow), (2) only the materials it may use, (3) rules for when to stop, (4) what to do on failure.

복사해서 Claude 대화창에 붙여넣기Copy & paste into a Claude chat

너는 고객 문의 답장 초안 도우미야. 역할은 딱 하나 — 내가 붙여 넣는 고객 문의(반품·교환·배송지연 관련)를 읽고, 정중한 답장 '초안'을 잡아 주는 것. 너는 초안만 만들고, 실제 발송은 사람이 한다.You are a customer-inquiry reply-draft assistant. You have exactly one job — read the customer inquiry I paste in (about returns, exchanges, or delivery delays) and put together a polite reply "draft." You only make the draft; a human does the actual sending.

## 할 일## What to do

내가 고객 문의 한 건을 주면, 아래를 정리해서 돌려줘.When I give you one customer inquiry, organize and return the following.

  1. 문의 유형: 반품 / 교환 / 배송지연 중 무엇인지 한 줄로.Inquiry type: which of return / exchange / delivery delay it is, in one line.
  2. 답장 초안: 정중한 존댓말로, 고객을 안심시키되 우리가 약속할 수 있는 범위만 담아.Reply draft: in polite language, reassuring the customer but containing only what we can actually promise.
  3. 확인 필요: 답장에 들어가야 하는데 문의 글만으로는 알 수 없는 정보(주문번호, 환불 규정 등)를 목록으로.Needs confirmation: a list of information the reply needs but that can't be known from the inquiry alone (order number, refund policy, etc.).

## 쓸 자료## Materials to use

  • 내가 이번에 붙여 넣은 고객 문의 글, 그것만 근거로 삼아. 우리 환불 규정이나 배송 정책을 네가 일반 상식으로 추측해서 답장에 적지 마.Base it only on the customer inquiry I pasted this time. Don't guess our refund policy or delivery policy from general knowledge and write it into the reply.

## 멈춤 규칙 (애매하면 추측하지 말고 물어봐)## Stop rules (if unclear, ask instead of guessing)

  • 우리 규정에 따라 달라지는 약속(예: "무료 반품 됩니다", "내일까지 도착합니다")은 임의로 단정하지 말고, "이 건은 무료 반품 대상이 맞나요?"처럼 나에게 먼저 물어봐.For promises that depend on our policy (e.g., "free returns apply," "it'll arrive by tomorrow"), don't assert them on your own — ask me first, like "Does this case qualify for a free return?"
  • 답장 초안 작성 외의 요청(예: "고객한테 바로 발송해줘", "환불 처리도 해줘")은 네 역할 밖이야. 하지 말고, 역할 밖이라고 알려줘.Requests beyond drafting a reply (e.g., "send it to the customer right away," "process the refund too") are outside your role. Don't do them — tell me they're out of scope.

## 실패 시 행동## What to do on failure

  • 주문번호·구매일·금액처럼 문의 글에 없는 정보는 아무 값이나 지어내지 마. 답장 초안에서는 '[주문번호 확인 필요]'처럼 빈칸으로 표시하고, '확인 필요' 목록에 올려.Don't invent any value for information not in the inquiry, like order number, purchase date, or amount. In the reply draft, mark it as a blank like "[order number needs confirmation]" and add it to the "needs confirmation" list.
  • 붙여 넣은 글이 반품·교환·배송지연 어디에도 해당하지 않으면, 억지로 답장을 만들지 말고 "이 문의는 반품/교환/배송지연 유형으로 확인되지 않습니다"라고 답해.If the pasted text fits none of return, exchange, or delivery delay, don't force a reply — answer "This inquiry isn't confirmed as a return/exchange/delivery-delay type."
  1. 만들기: Claude 대화창을 열고 위 지시문을 그대로 붙여 넣는다. (역할이 한 줄로 좁은지 — '답장 초안만, 발송은 사람', 쓸 자료가 '이번 문의 글'로 한정됐는지, 멈춤 규칙과 실패 시 행동이 글로 다 적혀 있는지 확인) 그런 다음 실제 고객 문의 한 건을 붙여 넣어 답장 초안을 받아 본다.Build it: Open a Claude chat and paste in the instruction above. (Check that the role is one narrow line — "drafts only, a human sends," the materials are limited to "this inquiry," and the stop rules and failure actions are all written down.) Then paste in a real customer inquiry and look at the reply draft.
  2. 여러 번 시켜 일관성 보기: 같은 문의를 새 대화에서 2~3번 더 처리시켜 본다. 문의 유형 판정과 답장 톤·약속 범위가 매번 비슷하게 나오면 설계가 안정적인 것이고, 어떤 답장은 무료 반품을 단정하고 어떤 답장은 안 그러는 식으로 들쭉날쭉하면 지시문이 더 또렷해져야 한다는 신호다.Run it several times for consistency: Have it process the same inquiry 2-3 more times in fresh chats. If the inquiry-type call and the tone and scope of promises in the reply come out similar every time, the design is stable; if one draft flatly promises a free return and another doesn't, that's a signal the instruction needs to be sharper.
  3. 까다로운 입력으로 멈춤·실패 확인: 일부러 경계 상황을 준다 — (a) 주문번호·구매일이 빠진 문의, (b) "환불해 주실 거죠?"처럼 우리 규정을 확인해야만 답할 수 있는 문의, (c) "확인했으면 고객한테 바로 답장 보내고 환불도 처리해줘"라는 역할 밖 요청. 없는 정보를 지어내지 않고 '[확인 필요]'로 표시하거나, 규정 대상이 맞는지 되묻거나, 발송·환불은 역할 밖이라고 멈추면 설계가 통과한 것이다.Probe stops and failures with tricky input: Deliberately give it edge cases — (a) an inquiry missing the order number and purchase date, (b) an inquiry like "You'll refund me, right?" that can only be answered by checking your own policy, and (c) an out-of-scope request like "once you've checked, just send the reply to the customer and process the refund too." If it marks missing info as "[needs confirmation]" instead of inventing it, asks back whether the case actually qualifies under policy, or stops because sending and refunding are out of scope, the design passes.

전체 대본Full transcript

1 · 오프닝 — 환경을 설계하라1 · Opening — Design the environment

지난 시간에 우리는 Claude에 팔다리를 붙였습니다. 엠씨피로 바깥세상에 닿게 하고, 훅으로 자동 반응을 걸고, 커스텀 도구를 쥐여 줬죠. 그리고 마지막에 이런 예고를 했어요. 팔다리가 많아지면, 통째로 위임할 일꾼이 필요하다고요. 그 일꾼이 바로 에이전트입니다. 그런데 여기서 중요한 건, 일꾼의 성능은 머리, 그러니까 모델이 아니라, 일하는 환경이 가른다는 점이에요. 같은 Claude라도 어떤 도구를 쥐여 주고, 어떤 지침을 박아 두고, 어디까지 범위를 한정했느냐에 따라 결과가 완전히 갈립니다. 그래서 오늘은 룰 넘버 써틴, 환경을 설계하라를 가지고, 에이전트를 직접 설계해 보겠습니다.Last time, we attached limbs to Claude. We let it reach the outside world with MCP, wired automatic reactions with Hooks, and handed it custom tools. And we closed with a teaser: as the limbs multiply, you'll need a worker to delegate to wholesale. That worker is the agent. But here's the key point — a worker's performance comes not from the brain, the model, but from the workplace it operates in. The same Claude splits into completely different results depending on which tools you hand it, which instructions you nail down, and how far you narrow its scope. So today, under Rule Number Thirteen — "design the environment" — we'll design an agent ourselves.

2 · 같은 일꾼, 다른 결과2 · Same worker, different result

한 가지 장면을 볼게요. 사용자가 일꾼에게 이 일 좀 알아서 잘 해줘, 하고 통째로 맡깁니다. 그런데 어떤 도구를 써야 하는지, 어떤 기준으로 판단해야 하는지, 어디까지 손대도 되는지를 안 정해 줬어요. 그러니 일꾼은 매번 다른 방식으로, 때로는 엉뚱하게 일합니다. 어제는 이렇게 하고 오늘은 저렇게 하고요. 분명 같은 Claude인데, 결과가 들쭉날쭉합니다.Let's look at one scene. A user hands the whole job to a worker — "just handle this however you see fit." But they never specified which tools to use, what criteria to judge by, or how far it's allowed to reach. So the worker does it a different way each time, sometimes off the rails. One day this way, the next day that way. It's clearly the same Claude, yet the results are all over the place.

지난 시간 끝에 일꾼이 필요하다고 했죠. 그런데 일꾼을 부르는 것과, 일꾼을 설계하는 것은 완전히 다른 일입니다. 부탁은 할 때마다 말이 조금씩 달라지고, 그래서 결과도 매번 달라져요. 하지만 환경을, 그러니까 어떤 도구로 어떤 지침으로 어디까지를 한 번 설계해서 적어 두면, 그다음부터는 매번 같게 일합니다. 그래서 오늘의 질문은 이거예요. 일꾼이 매번 같게 일하도록, 환경을 어떻게 설계할까?At the end of last session I said you'd need a worker. But calling a worker and designing one are entirely different things. A request shifts a little in wording every time, so the result shifts too. But once you design the environment — which tools, which instructions, how far — and write it down, from then on it works the same every time. So today's question is this: how do you design the environment so the worker does it the same way every time?

3 · 에이전트 = Claude + 도구 + 지침3 · Agent = Claude + tools + instructions

그럼 에이전트가 정확히 뭔지부터 짚고 갈게요. 많은 분들이 에이전트를 더 똑똑한 모델 정도로 오해하시는데요. 그렇지 않습니다. 에이전트는 세 가지의 조합이에요. 첫째 Claude, 그러니까 모델. 둘째 쥐여 줄 도구 묶음. 셋째 어떻게 일할지를 적은 지침과 역할. 이 셋을 합친 게 하나의 에이전트입니다. 공식 문서에서도 서브에이전트를 이렇게, 모델과 사용할 도구와 시스템 지침의 조합으로 정의해요.So let's pin down exactly what an agent is. A lot of people mistake an agent for some kind of smarter model. It isn't. An agent is a combination of three things. First, Claude — the model. Second, the set of tools you hand it. Third, the instructions and role that say how it should work. Combine those three and you have one agent. The official docs define a subagent this exact way — a combination of a model, the tools it can use, and a system instruction.

여기서 핵심 함의가 나옵니다. 같은 Claude라도 도구를 바꾸고, 지침을 바꾸고, 범위를 바꾸면, 완전히 다른 일꾼이 돼요. 머리는 그대로인데 일하는 모습이 달라지는 거죠. 그러니까 성능은 머리에서 나오는 게 아니라, 환경 설계에서 나옵니다. 그리고 지난 시간에 붙인 그 팔다리들, 엠씨피랑 훅이랑 커스텀 도구가 바로 여기 도구 자리에 들어가요. 에이전트를 부른다고 생각하지 말고, 조합으로 설계한다고 생각하세요. 정의에 들어가는 항목 이름은 버전마다 바뀌니까, 정확한 형식은 그때그때 공식 문서로 확인하시고요.And here's the key implication. Take the same Claude, swap the tools, swap the instructions, swap the scope — and you get a completely different worker. The brain is unchanged, but how it works is transformed. So performance doesn't come from the brain; it comes from environment design. And those limbs we attached last time — MCP, Hooks, custom tools — they slot right into this "tools" position. Don't think of calling an agent; think of designing one by combination. The names of the fields in a definition change from version to version, so check the exact format in the official docs each time.

4 · 무엇을 설계하나4 · What you design

그럼 에이전트를 설계한다는 게 구체적으로 뭘 적는 거냐. 대표적으로 네 가지예요. 표를 같이 보시죠. 첫째, 역할과 설명. 이 에이전트가 언제 불려 나오는지를 정합니다. 그래야 엉뚱한 일에 끼어들지 않아요. 둘째, 지침. 어떻게 일할지를 정합니다. 시스템 프롬프트라고 보시면 돼요. 이게 있어야 매번 같은 기준으로 일합니다. 셋째, 도구 범위. 쥐여 줄 도구만 정확히 정해요. 권한을 좁히면 사고 범위도 좁아집니다. 넷째, 모델. 일의 체급을 정합니다. 어려운 일이면 오퍼스, 가벼운 일이면 하이쿠, 이런 식으로요.So what exactly do you write down when you design an agent? Representatively, four things. Let's look at the table together. First, the role and description — you set when this agent gets called. That keeps it from butting into the wrong job. Second, the instructions — how it should work. Think of it as the system prompt. This is what makes it work by the same criteria every time. Third, the tool scope — you specify exactly which tools to grant. Narrow the power and you narrow the blast radius. Fourth, the model — the weight class for the work. Opus for hard jobs, Haiku for light ones, that sort of thing.

이 네 가지를 적어 두는 것, 이게 곧 환경 설계예요. 핵심은, 머릿속에만 두지 말고 파일에 적는다는 겁니다. 부탁은 휘발하지만, 파일에 적은 설계는 남아서 매번 똑같이 적용되거든요. 한 가지 주의할 점. 방금 말한 네 항목의 이름이나 형식은 버전마다, 환경마다 조금씩 다릅니다. 그러니까 이 네 개가 전부다, 이 이름이 고정이다, 이렇게 외우지 마시고, 정확한 건 이천이십육 년 육월 기준으로 공식 문서에서 확인하세요. 중요한 건 항목 이름이 아니라, 역할과 지침과 도구와 체급을 글로 못 박는다는 원리입니다.Writing down these four things — that's environment design. The key is this: don't keep it in your head, put it in a file. A request evaporates, but a design written in a file stays and applies identically every time. One caution: the names and formats of those four items differ slightly by version and by environment. So don't memorize "these four are everything" or "these names are fixed." Check the exact details in the official docs, as of June twenty twenty-six. What matters isn't the item names, but the principle of nailing down role, instructions, tools, and weight class in writing.

5 · 나쁜 정의 vs 좋은 정의5 · Bad definition vs good definition

그럼 좋은 설계와 나쁜 설계가 어떻게 다른지 비교해 볼게요. 왼쪽이 나쁜 정의입니다. 역할이 막연해요. 이것저것 다 하는 도우미, 이런 식이죠. 그리고 도구는 있는 대로 다 줍니다. 언제 멈출지, 뭘 돌려줄지 기준도 없고요. 이러면 일꾼이 매번 다르게 일할 수밖에 없어요. 고를 수 있는 게 너무 많고, 따라야 할 기준이 없으니까요.So let's compare how a good design differs from a bad one. On the left is the bad definition. The role is vague — a "does-everything helper," that kind of thing. And it's handed every tool available. There's no criterion for when to stop or what to return. With this, the worker can't help but work differently every time, because there's too much to choose from and no standard to follow.

오른쪽이 좋은 정의예요. 역할이 한 줄로 또렷합니다. 필요한 도구만 정확히 쥐여 주고요. 그리고 언제 멈출지, 무엇을 반환할지가 명시돼 있어요. 그러면 매번 같게 일합니다. 여기서 많은 분들이 오해하시는 게 있어요. 도구를 많이 줘야 똑똑해진다고 생각하시는데, 오히려 반대예요. 범위를 좁히는 게 곧 신뢰를 높이는 겁니다. 범위가 좁을수록 행동이 예측 가능하고, 그래서 더 안전하고 일관돼요. 그러니까 처음부터 좁게 설계하세요.On the right is the good definition. The role is sharp, in a single line. Only the needed tools are handed over, precisely. And when to stop and what to return are spelled out. With that, it works the same every time. Here's where many people get it wrong: they think handing over more tools makes it smarter. It's the opposite. Narrowing the scope is how you raise trust. The narrower the scope, the more predictable the behavior — and so the safer and more consistent it is. So design it narrow from the start.

6 · 역할은 좁고 또렷하게6 · Make the role narrow and sharp

왜 좁히는 게 좋은지, 세 가지로 따져볼게요. 범위가 넓으면 이렇게 됩니다. 첫째, 고를 도구가 너무 많아서 헤매요. 둘째, 권한이 크니까 사고가 났을 때 그 사고 범위도 큽니다. 셋째, 다 하라고 하니 지침이 두루뭉술해지죠. 반대로 범위가 좁으면, 고를 게 적어서 빠르고 일관되고, 권한이 좁아서 사고가 나도 범위가 작고, 역할이 또렷합니다. 지난 시간에 권한은 좁게 줘라, 했던 거랑 똑같은 원리예요.Let me reason through why narrowing is better, in three points. With a broad scope, this happens. One: there are too many tools to choose from, so it wanders. Two: with great power, when something goes wrong, the blast radius is big too. Three: since you've told it to do everything, the instructions turn fuzzy. Conversely, with a narrow scope, there's little to choose from, so it's fast and consistent; the power is small, so even a mishap stays small; and the role is sharp. It's the same principle as last time, when I said grant power narrowly.

그리고 한 가지 더, 컨텍스트 측면이 있어요. 도구와 지침이 많을수록, 그 정의 자체가 컨텍스트를 더 많이 차지합니다. 책상 위에 일꾼 설명서가 두꺼우면, 정작 일할 자리가 줄어드는 거죠. 정확히 몇 토큰을 더 먹느냐는 환경마다 다르니까 숫자로 단정하진 않을게요. 핵심은 방향이에요. 적게 줄수록 가볍고, 일관되고, 안전하다. 그러니까 다 주지 말고, 딱 필요한 만큼만 쥐여 주세요. 룰 넘버 투, 컨텍스트를 보호하라와도 맞닿아 있습니다.And one more thing — the context side. The more tools and instructions there are, the more the definition itself takes up context. If the worker's manual on the desk is thick, there's less room left to actually work. Exactly how many more tokens it eats varies by environment, so I won't put a number on it. The point is the direction: the less you grant, the lighter, the more consistent, the safer. So don't grant everything — hand over exactly as much as is needed. This ties right into Rule Number Two, protect the context.

7 · 도구는 최소로7 · Minimize the tools

이제 오늘 강의의 심장입니다. 똑같은 Claude를 두 개의 다른 환경에 넣어 볼게요. 환경 에이는 도구가 좁게 정해져 있고 지침이 또렷합니다. 환경 비는 모든 도구가 다 열려 있고 지침은 막연해요. 머리는 완전히 똑같은데, 환경 에이에서는 행동이 일관됩니다. 매번 비슷하게 일해요. 그런데 환경 비에서는 제멋대로 행동합니다. 매번 다르게요. 모델이 같은데도 결과가 갈리는 거죠.Now for the heart of today's talk. Let's drop the exact same Claude into two different environments. Environment A has tools narrowly defined and sharp instructions. Environment B has every tool wide open and vague instructions. The brain is completely identical, yet in Environment A the behavior is consistent — it works similarly every time. In Environment B it goes off on its own — different every time. Same model, and still the results diverge.

이게 룰 넘버 써틴의 핵심이에요. 에이전트의 행동은 모델 능력보다, 주어진 환경에 훨씬 크게 좌우됩니다. 어떤 도구를 줬고, 어떤 지침을 박았고, 범위가 어디까지고, 맥락이 어떤지. 그래서 결과를 개선하고 싶을 때 1차 레버는 더 똑똑한 모델을 찾는 게 아니라, 더 나은 환경을 설계하는 거예요. 결과가 나쁘게 나오면, 모델 탓을 하기 전에 환경부터 보세요. 모델을 바꾸기 전에 환경을 바꾼다. 이걸 기억하시면 됩니다.This is the core of Rule Number Thirteen. An agent's behavior is governed far more by the environment it's given than by the model's raw ability — which tools you gave it, which instructions you nailed in, how far the scope reaches, what context it has. So when you want to improve the result, the first lever isn't hunting for a smarter model — it's designing a better environment. When the result comes out badly, before you blame the model, look at the environment first. Change the environment before you change the model. Remember that.

8 · 실패를 전제로 설계8 · Design for failure

일꾼은 반드시 넘어집니다. 그래서 잘 설계된 에이전트는 잘 될 거라고 가정하지 않고, 실패할 거라고 가정하고 설계해요. 표를 보시죠. 첫째, 도구가 에러를 돌려줄 때. 나쁜 에이전트는 그 에러를 무시하고 그냥 진행합니다. 설계된 에이전트는 에러를 읽고, 재시도하거나 다른 경로로 돌아가요. 둘째, 결과가 비었거나 이상할 때. 나쁜 에이전트는 그 빈칸을 그럴듯하게 채웁니다. 이게 바로 3강에서 본 할루시네이션이죠. 설계된 에이전트는 채우지 않고, 확인 못 했다고 솔직하게 반환합니다.A worker will absolutely stumble. So a well-designed agent doesn't assume it'll go fine — it's designed assuming it'll fail. Look at the table. First, when a tool returns an error. A bad agent ignores the error and just marches on. A designed agent reads the error and retries, or reroutes another way. Second, when the result is empty or off. A bad agent fills that blank in plausibly — that's exactly the hallucination we saw last lecture. A designed agent doesn't fill it; it honestly returns "couldn't confirm."

셋째, 막혔는데 계속 시도하는 경우. 나쁜 에이전트는 같은 자리에서 무한 반복합니다. 설계된 에이전트는 정해 둔 한도에서 멈추고 사람에게 보고해요. 여기서 핵심은 이겁니다. 에러 처리를 안 해 두면, 에이전트는 성공적으로 사고를 냅니다. 멈추지 않고 끝까지 가서, 틀린 걸 그럴듯하게 완성해 버리거든요. 그러니까 잘 되는 길만 설계하지 말고, 틀리는 길을 먼저 설계하세요. 도구가 실패하면? 결과가 비면? 막히면? 이 세 질문에 미리 답을 적어 두는 겁니다.Third, when it's stuck but keeps trying. A bad agent loops forever in the same spot. A designed agent stops at a preset limit and reports to a human. Here's the key: if you don't handle errors, the agent will fail successfully. It won't stop — it'll run all the way to the end and finish something wrong, plausibly. So don't only design the happy path — design the failure path first. What if the tool fails? What if the result is empty? What if it gets stuck? You write the answers to these three questions in advance.

9 · 멈춤은 설계된 안전장치9 · Stopping is a designed safeguard

좋은 일꾼의 조건은 끝까지 해내는 게 아니에요. 멈출 때를 아는 겁니다. 끝까지 밀어붙이는 일꾼은 오히려 위험해요. 그래서 어떤 신호가 오면 멈춰야 하는지를 설계에 넣어 둡니다. 네 가지예요. 첫째, 처음에 세운 가정이 틀렸다는 증거가 나왔을 때. 둘째, 권한이나 범위 밖의 일을 하려고 할 때. 이건 설계로 막아 둔 선이죠. 셋째, 같은 시도를 계속 반복하고 있을 때. 루프에 빠진 거예요. 넷째, 사람의 판단이 필요한 갈림길에 섰을 때.The mark of a good worker isn't finishing no matter what — it's knowing when to stop. A worker that pushes through to the end is, if anything, dangerous. So you build into the design which signals should make it stop. Four of them. First, when evidence appears that the assumption it started with was wrong. Second, when it's about to do something outside its power or scope — that's a line you drew in the design. Third, when it's repeating the same attempt over and over — it's fallen into a loop. Fourth, when it stands at a fork that needs human judgment.

여기서 중요한 관점 전환이 있어요. 멈춤은 실패가 아닙니다. 설계된 안전장치예요. 지난번에 중간에 멈춰서 확인하라고 한 거, 그리고 프리 툴 유즈 가드로 위험한 도구 호출을 미리 막은 거 기억나시죠? 그거랑 똑같은 원리입니다. 에이전트한테도 언제 멈출지를 시작할 때 미리 적어 두면, 폭주하지 않아요. 끝까지 가서 사고 치는 일꾼보다, 애매할 때 멈춰서 물어보는 일꾼이 훨씬 믿을 만합니다.Here's an important shift in perspective. Stopping isn't failure — it's a designed safeguard. Remember last time, when I said stop midway and check, and how a PreToolUse guard blocks a dangerous tool call in advance? Same principle. If you write down for the agent, up front, when it should stop, it won't go rogue. A worker that stops and asks when things are murky is far more trustworthy than one that runs to the end and causes a mess.

10 · 배포 전 테스트10 · Test before you deploy

설계를 다 했으면, 바로 믿고 쓰면 될까요? 아닙니다. 에이전트도 배포 전에 테스트를 해요. 사람 신입한테 일을 맡기기 전에 몇 번 시켜 보는 거랑 똑같습니다. 세 가지를 봐요. 첫째 일관성. 같은 입력을 여러 번 줬을 때 매번 비슷한 결과가 나오는지. 둘째 범위 준수. 일부러 범위 밖의 일을 줘 보고, 그걸 거부하거나 멈추는지. 셋째 실패 대응. 일부러 에러 상황을 만들어 줬을 때, 빈칸을 채우지 않고 솔직하게 보고하는지.Once you've finished the design, can you just trust it and go? No. You test an agent before you deploy it too. It's just like giving a new hire a task a few times before you hand them the real thing. You check three things. First, consistency: when you give the same input several times, do you get a similar result every time? Second, scope adherence: deliberately give it an out-of-scope job and see if it refuses or stops. Third, failure handling: manufacture an error on purpose and see whether it reports honestly instead of filling in the blank.

핵심은 이거예요. 한 번 잘 됐다고 믿지 마세요. 한 번 성공은 운일 수도 있거든요. 여러 번, 그리고 경계에서 시켜 봐야 설계가 진짜 검증됩니다. 경계라는 건, 범위의 가장자리나 일부러 실패시키는 상황을 말해요. 11강에서 도구가 낸 결과를 다시 읽어서 검증하라고 했죠. 에이전트도 똑같습니다. 에이전트가 낸 결과도 다시 읽고, 여러 번 돌려 보세요. 신뢰는 기대로 얻는 게 아니라, 테스트로 얻습니다.Here's the key: don't trust one success. One success might just be luck. You only truly verify the design by running it many times, and at the edges. By "edges" I mean the boundary of the scope, or situations you deliberately make fail. Last lecture I said reread the tool's output and verify it. Same for agents. Reread what the agent produced, and run it several times. Trust isn't earned by expectation — it's earned by testing.

11 · 설계 체크리스트11 · Design checklist

자, 오늘의 완성형입니다. 일꾼을 내보내기 전에 다섯 가지만 점검하세요. 첫째, 역할이 한 줄로 또렷한가? 이것저것 다 하는 도우미가 아니라, 한 문장으로 설명되는 역할이어야 합니다. 둘째, 도구를 필요한 만큼만 쥐여 줬나? 다 주지 말고 권한을 한정하세요. 셋째, 언제 멈출지, 그러니까 중단 조건을 적었나? 이게 폭주를 막는 선입니다.Alright, today's peak. Before you deploy the worker, check just five things. One: is the role sharp in one line? Not a does-everything helper, but a role describable in a single sentence. Two: did you grant only the tools needed? Don't grant everything — bound the power. Three: did you write when to stop, the stop conditions? That's the line that prevents a runaway.

넷째, 실패하면 어떻게 할지, 에러 핸들링을 적었나? 잘 되는 길 말고 틀리는 길을 먼저 적으세요. 다섯째, 여러 번 그리고 경계에서 테스트했나? 한 번 성공했다고 믿으면 안 됩니다. 재밌는 건, 이 다섯 가지가 앞에서 본 슬라이드들과 정확히 하나씩 짝을 이룬다는 거예요. 역할은 좋은 정의, 도구는 범위 한정, 멈춤은 중단 조건, 실패는 에러 핸들링, 테스트는 테스트법. 에이전트는 부르면 끝이 아니라, 환경을 적어서 내보내는 겁니다. 설계가 절반, 테스트가 절반이에요.Four: did you write how it fails — the error handling? Write the failure path before the happy path. Five: did you test it many times, and at the edges? You can't trust it just because it succeeded once. Here's the fun part: these five map exactly, one by one, onto the slides we saw earlier. Role is the good definition, tools is scope-narrowing, stopping is the stop conditions, failure is error handling, and testing is the test method. An agent isn't done when you call it — you deploy it by writing the environment. Design is half, testing is the other half.

12 · 실습12 · Exercise

다섯 가지를 한 줄로 정리해볼게요. 역할은 좁게, 도구는 최소로, 멈춤과 실패는 미리, 그리고 테스트. 좋은 에이전트는 또렷한 역할에, 최소한의 도구에, 멈출 때와 실패 대응을 더한 다음, 여러 번 테스트하고 나서야 신뢰하는 겁니다. 오늘의 룰 넘버 써틴은 사실 앞에서 배운 규칙들이 다 만나는 지점이에요. 룰 넘버 파이브, 명령 대신 설계하라. 룰 넘버 일레븐, 도구를 써라. 룰 넘버 트웰브, 권한은 좁게. 이게 다 환경 설계로 모입니다. 환경을 한번 설계해 두면, 매번 부탁하지 않아도 같은 결과가 나와요.Let me lock the five into one line. Narrow the role, minimize the tools, pre-plan the stops and failures, then test. A good agent is a sharp role plus minimal tools plus when-to-stop plus failure handling — and only then, after testing many times, do you trust it. Today's Rule Number Thirteen is really where all the rules we've learned converge. Rule Number Five, design instead of command. Rule Number Eleven, use tools. Rule Number Twelve, grant power narrowly. They all gather into environment design. Once you've designed the environment, the same result comes out without you having to ask every time.

13 · 핵심 정리13 · Key takeaways

오늘 처음에 봤던 그 장면, 알아서 잘 해줘로 돌아가 볼게요. 설계 없이 일하는 사람은, 일이 생길 때마다 알아서 해줘를 다시 부탁합니다. 그런데 말이 매번 조금씩 다르니까 결과도 매번 달라요. 반면 환경을 설계한 사람은, 역할과 도구와 멈춤과 실패를 한 번 적어 뒀습니다. 그래서 매번 같게 일하죠. 똑같은 Claude, 똑같은 일인데, 한쪽은 들쭉날쭉하고 다른 쪽은 일정합니다. 부탁은 휘발하지만, 설계는 남아요. 결과의 일관성은 더 똑똑한 모델이 아니라 환경 설계에서 옵니다. 이게 바로 룰 넘버 써틴의 핵심이에요.Let's go back to that opening scene — "just handle it well." Someone who works without a design re-asks "just handle it" every time a job comes up. But the wording shifts a little each time, so the result shifts each time. Someone who designed the environment, on the other hand, wrote down the role, the tools, the stops, and the failures once. So it works the same every time. Same Claude, same job, and yet one side is erratic and the other is steady. A request evaporates; a design stays. Consistency of results comes not from a smarter model but from environment design. That is the core of Rule Number Thirteen.

14 · 마무리 · 다음 강 예고14 · Wrap-up · next lesson

오늘 한 문장만 가져가신다면, 이겁니다. 일꾼을 바꾸지 말고, 일터를 설계하라. 결과가 마음에 안 들 때 더 똑똑한 모델을 찾기 전에, 일하는 환경부터 설계하세요. 순서는 네 단어로 기억하시면 됩니다. 역할, 도구, 멈춤과 실패, 그리고 테스트. 정의 파일의 필드 이름이나 옵션은 앞으로 계속 바뀌겠지만, 역할은 좁게, 도구는 최소로, 멈춤과 실패는 미리, 그리고 테스트, 이 원리는 그대로 갑니다. 그런데 오늘은 일꾼 하나를 잘 설계하는 법을 배웠죠. 다음 시간에는, 이 잘 만든 일꾼들을 여러 명 모아서 하나의 팀으로 조율하는 법, 멀티에이전트와 하네스를 다뤄 보겠습니다. 혼자 쓰지 말고, 팀을 만드는 거예요.If you take one sentence from today, it's this: don't swap the worker — design the workplace. When you don't like the result, before you hunt for a smarter model, design the environment it works in first. Remember the order in four words: role, tools, stops and failures, and test. The field names and options in a definition file will keep changing, but the principle — narrow the role, minimize the tools, pre-plan the stops and failures, then test — stays the same. But today we learned how to design one worker well. Next time, we'll cover how to gather several of these well-built workers and orchestrate them into a single team — multi-agents and the harness. Don't work alone; build a team.