복잡한 Agent 요청, 끝까지 확인하며 맡기는 법

“알아서 해 주세요”로는 부족해지는 순간

간단한 질문은 한 번의 답으로 끝납니다. 하지만 다음 요청은 다릅니다.

공식 자료를 먼저 찾아야 합니다.
자료를 바탕으로 글을 써야 합니다.
글 속 주장을 다시 출처와 대조해야 합니다.
파일 형식과 빌드도 확인해야 합니다.
공개 게시 전에는 사용자의 승인을 받아야 합니다.

이런 일은 앞 단계의 결과가 다음 단계의 입력이 됩니다. 조사 전에 결론부터 쓰면 근거가 약해지고, 검증 전에 게시하면 되돌리기 어려운 문제가 생깁니다. 사용자가 원하는 것은 단순히 “Agent가 바쁘게 움직이는 모습”이 아닙니다. 일이 빠지지 않고 올바른 순서로 이어지고, 마지막 결과를 직접 확인할 수 있는 상태입니다.

좋은 소식은 내부 도구 이름이나 명령을 외울 필요가 없다는 점입니다. 요청할 때 다섯 가지만 분명히 해 주세요.

바로 복사해서 쓰는 요청문

결과: [최종 결과물]을 만들어 주세요.
순서: 먼저 [1단계], 다음으로 [2단계], 마지막으로 [3단계]를 진행해 주세요.
제약: [하지 말아야 할 일, 사용할 자료, 형식, 범위]를 지켜 주세요.
검증: 완료 전에 [확인할 항목과 검사 방법]을 확인하고 근거를 함께 주세요.
승인: [게시, 배포, 삭제, 외부 전송, 운영 변경] 전에는 멈추고 제 승인을 받아 주세요.

예를 들어 기술 글을 맡긴다면 이렇게 쓸 수 있습니다.

결과: 공식 문서를 바탕으로 초보자용 한국어 안내 글을 작성해 주세요.
순서: 근거와 개요를 만들고, 초안을 쓴 뒤, 마지막에 주장과 출처를 확인해 주세요.
제약: 공식 자료를 우선하고 확인하지 못한 기능은 단정하지 마세요. 원본 저장소는 수정하지 마세요.
검증: 필수 목차, 출처, MDX 형식, 빌드 결과를 확인하고 파일을 전달해 주세요.
승인: 공개 게시, 저장소 반영, 외부 전송 전에는 제 승인을 받아 주세요.

다섯 입력은 각각 다른 실패를 막습니다.

결과는 어디까지 해야 끝인지 정합니다.
순서는 먼저 확인해야 할 일을 건너뛰지 않게 합니다.
제약은 범위가 커지거나 원치 않는 변경이 생기는 것을 막습니다.
검증은 “완료했습니다”를 확인 가능한 결과로 바꿉니다.
승인은 외부 영향이 생기기 전에 사용자가 결정권을 갖게 합니다.

순서를 잘 모르겠다면 “안전한 순서를 정해 진행하되, 마지막에 모든 요구사항을 확인해 주세요”라고 적어도 됩니다. 중요한 것은 Agent가 추측해야 하는 부분을 줄이는 일입니다.

사용자는 진행 중에 무엇을 보게 될까요?

복잡한 요청을 맡겼다고 해서 내부 상태를 계속 지켜볼 필요는 없습니다. 좋은 진행 알림은 양이 아니라 의미가 중요합니다.

단계가 바뀔 때 받는 짧은 소식

공식 자료와 개요를 확인했습니다.
개요를 바탕으로 초안을 작성하고 있습니다.
검증에서 출처가 부족한 문장을 찾아 수정했습니다.

“작업 중입니다”를 반복하는 알림보다 무엇이 끝났고 무엇이 다음인지 알려 주는 알림이 유용합니다.

결정이 꼭 필요할 때 받는 질문

게시 승인, 삭제 범위, 상충하는 기준처럼 Agent가 안전하게 대신 정할 수 없는 문제가 생기면 질문을 받습니다. 질문은 실패가 아닙니다. 사용자의 결정권이 필요한 경계에서 정확히 멈춘 것입니다.

좋은 질문에는 세 가지가 함께 있습니다.

지금 멈춘 이유
선택 가능한 2~3개 방법과 추천안
선택에 따라 달라지는 결과

마지막에 받는 결과와 근거

최종 답에는 결과물뿐 아니라 확인 근거가 있어야 합니다.

작성한 파일이나 링크
실행한 검사와 통과 여부
확인한 공식 출처
필수 요구사항 점검 결과
아직 확인하지 못한 제한 사항

완료 표시는 기록입니다. 정확성은 별도의 검증 근거가 뒷받침해야 합니다.

요청은 뒤에서 어떻게 실행 계획으로 바뀔까요?

여러 단계의 일은 Workboard라는 agent-local 작업판에 나눠 담을 수 있습니다. 냉장고에 붙인 계획표나 여행 전 체크리스트를 떠올리면 됩니다.

아래 도식은 사용자 요청이 검증된 결과로 이어지는 가장 단순한 흐름입니다.

flowchart TD
  A[사용자 요청] --> B[계획과 카드]
  B --> C[순서대로 실행]
  C --> D[결과 검증]
  D --> E{승인 필요?}
  E -->|예| F[사용자 결정]
  E -->|아니요| G[결과와 근거]
  F --> G

카드 한 장에는 보통 다음 정보가 담깁니다.

만들 결과와 범위
하지 않을 일과 사용할 자료
먼저 끝나야 하는 선행 작업
완료 기준과 확인 방법
외부 영향이 생기는 승인 경계
결과 파일, 링크, 검사 기록 같은 증거

이 정보를 원래 대화에만 남겨 두지 않고 작업 단위에 붙이면, 실행을 맡은 worker도 무엇을 해야 하는지 분명히 알 수 있습니다. worker는 카드에 적힌 사양과 완료된 선행 결과를 중심으로 작업하므로 카드의 설명 자체가 충분히 구체적이어야 합니다.

lifecycle과 dependency, 조금 더 자세히 보기

기본 흐름은 다음과 같습니다.

flowchart TD
  A[todo] -->|선행 조건 충족| B[ready]
  B -->|claim| C[running]
  C -->|결과와 proof| D[review]
  C -->|진행 불가| E[blocked]
  E -->|원인 해결| B
  D -->|기준 통과| F[done]
  D -->|보완 필요| B

이 상태는 “정답”을 자동으로 보증하는 점수가 아니라, 일이 어디까지 진행됐는지 기록하는 표지입니다.

1. todo와 ready: 시작 조건을 확인합니다

todo는 해야 할 일이지만 아직 선행 조건이 끝나지 않았을 수 있다는 뜻입니다. 필요한 앞 단계가 끝나면 ready가 되어 실행 후보가 됩니다. 순서가 없는 작업은 함께 준비될 수 있고, 반드시 앞뒤가 있어야 하는 작업은 dependency로 연결됩니다.

예를 들어 근거 조사, 초안, 검증을 선행 관계로 연결하면 근거가 준비되기 전에 초안 카드가 먼저 실행되는 일을 줄일 수 있습니다. 선행 카드가 끝났다는 기록만 믿지 않고, 다음 카드는 전달받은 결과가 자신의 입력 기준을 충족하는지도 확인해야 합니다.

2. claim과 running: 누가 실행 중인지 기록합니다

준비된 카드를 worker가 맡으면 claim하고 running으로 진행합니다. claim은 “이 작업을 지금 누가 다루는가”를 조정하는 장치입니다. 동시에 여러 실행자가 같은 카드를 중복으로 잡는 혼선을 줄이지만, 정확히 한 번만 실행된다는 보증이나 결과의 품질 보증은 아닙니다.

긴 작업에서는 heartbeat로 실행 lease와 짧은 진행 신호를 갱신할 수 있습니다. 이것도 결과가 좋다는 증명은 아닙니다. 단지 작업이 살아 있고 어느 단계인지 파악하는 데 도움을 줍니다.

3. review와 proof: 완료 선언을 검사합니다

worker가 결과를 내면 소유 Agent는 완료 기준과 비교합니다. 파일이 실제로 있는지, 테스트가 통과했는지, 출처가 주장을 뒷받침하는지 확인합니다. 이때 남기는 proof는 다음처럼 구체적일수록 좋습니다.

npm run build가 종료 코드 0으로 끝났습니다.
필수 목차 12개가 모두 존재합니다.
출처 3개의 문서 경로와 지원 문장을 대조했습니다.
원본 저장소의 변경 파일이 0개입니다.

검토가 부족하면 보완 카드를 만들거나 다시 실행할 수 있습니다. 기준을 충족하면 done으로 닫고 다음 dependency가 진행될 수 있습니다.

4. blocked: 멈춤도 유용한 결과로 만듭니다

실제 진행을 막는 문제가 생기면 blocked로 기록합니다. 좋은 차단 사유는 “안 됩니다”에서 끝나지 않습니다.

차단 사유: 공식 출처 두 개의 설명이 충돌합니다.
필요한 결정: 공개 문서의 최신 날짜를 우선할지, 제품 담당자 확인을 기다릴지 선택해 주세요.
안전한 다음 단계: 출처별 차이를 표로 정리해 두었습니다.

사람의 판단이 필요한지, 다른 카드로 해결할 수 있는지, 제약을 바꾸면 진행 가능한지 알 수 있어야 합니다.

사례: 기술 안내 글 한 편을 맡긴다면

사용자가 “Workboard를 처음 접하는 사람을 위한 글을 만들어 주세요. 저장소는 수정하지 말고, 공식 근거와 빌드 검증까지 해 주세요”라고 요청했다고 해 보겠습니다.

Agent는 이 일을 다음처럼 나눌 수 있습니다.

카드 1. 근거와 형식 조사

결과: 공식 Guide의 관련 문장과 블로그 MDX 규칙을 정리합니다.
제약: 공식 문서를 우선하고 비공개 식별자나 secret을 기록하지 않습니다.
검증: content schema, 기존 게시물, package script, 출처 경로를 직접 확인합니다.
산출물: 주장과 출처를 연결한 evidence outline입니다.

카드 2. 사용자 중심 초안 작성

선행 조건: 카드 1이 완료되어야 합니다.
결과: 독자가 바로 복사할 요청문과 실제 사례가 있는 한국어 MDX 초안입니다.
제약: Workboard를 보편적인 Portal 기능처럼 표현하지 않습니다.
검증: 필수 목차, frontmatter, 도식, 금지 정보가 모두 확인되어야 합니다.

카드 3. 사실과 렌더링 검증

선행 조건: 카드 2가 완료되어야 합니다.
결과: 출처와 본문 주장을 대조하고 임시 복사본에서 build를 실행합니다.
제약: 원본 저장소는 바꾸지 않고 게시나 배포를 하지 않습니다.
검증: 검사 명령과 결과, 한계, 최종 파일을 남깁니다.

중간에 공식 문서가 Workboard의 Portal 제공을 확인해 주지 못했다면 그 기능을 Portal 기능처럼 안내하지 않습니다. 이것이 dependency의 실질적인 가치입니다. 단순히 세 칸을 순서대로 움직이는 것이 아니라, 앞 단계의 근거가 뒤 단계의 문장과 검증 기준을 바꿉니다.

Tasks와 Workboard는 무엇이 다를까요?

한 문장으로 구분하면 이렇습니다.

Tasks는 조직이 함께 보는 업무 기록판이고, Workboard는 Agent runtime이 복잡한 일을 순서대로 실행하고 검증하기 위해 사용하는 agent-local 작업판입니다.

flowchart TD
  A[조직의 약속] --> B[Tasks]
  C[Agent 세부 실행] --> D[실행 보드]
  B --> E{실행 필요?}
  E -->|예| D
  E -->|아니요| F[조직 기록 유지]
  D --> G[결과와 근거]
  G --> B

공식 Guide에 따르면 Portal Tasks는 조직 단위 Kanban과 목록, Task 상세, 상태, 담당자, 마감일, 활동, 댓글, 첨부, 통계, Milestone, CSV export를 제공합니다. GitHub 이슈나 Pull Request를 연결할 수도 있지만, 그 연결은 참조입니다. GitHub 항목을 생성·수정·병합하거나 상태를 실시간 동기화하지는 않습니다.

반면 Workboard는 실행을 맡은 Agent와 그 Agent가 dispatch한 worker가 보는 실행 계획입니다. 독립적인 다른 Agent가 함께 보는 조직 보드는 아닙니다. 조직의 약속과 결정은 Tasks에, Agent 내부의 세부 실행과 dependency는 Workboard에 둘 수 있습니다. 양쪽 상태를 맞춰야 한다면 그 연결 방법과 책임자를 명시해야 합니다.

진행, 차단, review, proof를 읽는 법

사용자는 내부 상태 이름보다 다음 네 질문에 집중하면 됩니다.

보고 받은 내용	확인할 질문	좋은 답의 예
진행	무엇이 끝났고 다음은 무엇인가요?	“근거 조사가 끝났고, 확인된 개요로 초안을 작성합니다.”
차단	어떤 결정이나 입력이 필요한가요?	“게시 권한이 없어 초안까지만 완료했습니다. 공개하려면 승인이 필요합니다.”
review	완료 기준과 실제 결과가 일치하나요?	“필수 목차 12개와 frontmatter schema를 대조했습니다.”
proof	제3자가 다시 확인할 수 있나요?	“실행한 build 명령, 종료 결과, 산출물 위치를 남겼습니다.”

proof는 거창한 감사 보고서일 필요가 없습니다. 작은 작업은 파일 존재 확인 하나면 충분할 수 있습니다. 중요한 것은 위험과 결과에 맞는 검증입니다. 운영 변경이라면 dry-run과 diff, 글이라면 출처와 build, 데이터 삭제라면 대상 목록과 백업 여부가 더 적절합니다.

안전과 가용성의 경계

Workboard가 실행 순서를 관리한다고 해서 새 권한이 생기지는 않습니다.

공개 게시, 배포, 삭제, 결제, 외부 메시지는 별도 승인이 필요할 수 있습니다.
secret이나 사람 계정은 전용 권한과 안전한 전달 경로가 필요합니다.
운영 환경 변경은 영향 범위, 되돌리기 방법, 승인 주체를 먼저 확인해야 합니다.
도구가 runtime에 보인다는 사실만으로 모든 고객에게 제공되거나 사용 권한이 있다는 뜻은 아닙니다.

공식 Guide도 image와 runtime에 기능이 존재하는 것과 Portal에서 소비자가 운영할 수 있는 기능을 구분합니다. 실제 session의 도구, runtime 상태, 조직 정책, 사용자의 명시적 권한이 우선합니다. 확인할 수 없는 기능을 내부 URL, shell 설정, credential로 억지로 활성화해서는 안 됩니다.

또한 Portal Task의 마감일은 약속과 추적을 위한 정보이지 Agent runtime scheduler가 아닙니다. 날짜를 적었다고 그 시각에 Agent가 자동 실행된다고 기대하면 안 됩니다. 자동 실행이 필요하다면 현재 환경에 공식적으로 제공되는 scheduling 경로와 승인 정책을 별도로 확인해야 합니다.

다시 쓸 수 있는 체크리스트

요청하기 전

최종 결과물을 한 문장으로 적었나요?
반드시 지켜야 할 순서가 있나요?
하지 않을 일과 허용 범위를 적었나요?
완료를 확인할 검사나 근거를 정했나요?
게시, 삭제, 배포, 외부 전송 전 승인 지점을 적었나요?

진행 중

알림이 실제 단계 변화나 결정 필요성을 알려 주나요?
막힌 이유와 필요한 다음 행동이 구체적인가요?
범위나 위험이 커졌다면 다시 승인을 요청했나요?
오래 걸린다는 신호와 유용한 진행을 혼동하지 않았나요?

완료를 받을 때

요청한 파일, 링크, 결과가 실제로 있나요?
실행한 검사와 통과 여부가 적혀 있나요?
출처가 핵심 주장을 직접 뒷받침하나요?
확인하지 못한 한계가 숨겨지지 않았나요?
승인하지 않은 게시나 변경이 일어나지 않았나요?

보이지 않는 자동화보다 확인 가능한 실행 과정

복잡한 일을 잘 맡긴다는 것은 내부 도구를 자세히 아는 일이 아닙니다. 결과, 순서, 제약, 검증, 승인을 분명히 말하고, 마지막에 결과와 proof를 함께 확인하는 일입니다.

Workboard는 요청을 작은 카드로 나누고 dependency를 연결하며, 진행과 차단과 검토를 기록하는 데 도움을 줍니다. 카드가 닫혔다고 결과가 자동으로 정확해지는 것은 아니므로 완료 기준과 proof를 함께 확인해야 합니다. Workboard는 조직의 Tasks를 대체하지 않으며, 사용할 수 있는 기능과 권한은 session과 조직 정책에 따라 달라집니다.

사용자는 이렇게 요청하면 충분합니다.

복잡한 일이라면 안전한 순서로 나눠 진행해 주세요. 의미 있는 단계에서만 알려 주고,
막히면 필요한 결정을 설명해 주세요. 마지막에는 결과물과 검증 근거를 함께 주세요.
외부 영향이 있는 행동 전에는 제 승인을 받아 주세요.

그 한 문장이 보이지 않는 자동화를, 확인하고 결정할 수 있는 실행 과정으로 바꾸는 출발점입니다.

Sources

ClawPod Guide, Tasks와 Milestone으로 작업 추적, 조직 Tasks의 범위, 완료 근거, 댓글·첨부, Milestone, GitHub 참조와 자동 실행의 경계.
ClawPod Guide, Memory와 Agent 설정, session과 subagent를 포함한 Agent 실행 정책 및 Portal 설정 범위.
ClawPod Guide, 숨겨진 Agent 기능의 소비자 제공 상태, runtime 도구와 소비자 제공·권한의 차이, Task 마감일과 scheduler의 구분.