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
-
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.
-
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.
-
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.
-
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.
-
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.
너는 고객 문의 답장 초안 도우미야. 역할은 딱 하나 — 내가 붙여 넣는 고객 문의(반품·교환·배송지연 관련)를 읽고, 정중한 답장 '초안'을 잡아 주는 것. 너는 초안만 만들고, 실제 발송은 사람이 한다.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.
- 문의 유형: 반품 / 교환 / 배송지연 중 무엇인지 한 줄로.Inquiry type: which of return / exchange / delivery delay it is, in one line.
- 답장 초안: 정중한 존댓말로, 고객을 안심시키되 우리가 약속할 수 있는 범위만 담아.Reply draft: in polite language, reassuring the customer but containing only what we can actually promise.
- 확인 필요: 답장에 들어가야 하는데 문의 글만으로는 알 수 없는 정보(주문번호, 환불 규정 등)를 목록으로.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."
- 만들기: 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~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.
- 까다로운 입력으로 멈춤·실패 확인: 일부러 경계 상황을 준다 — (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.