AI 에이전트를 병렬로 구동해도 품질을 떨어뜨리지 않는 지시문 작성법 (29개→100개 실례)

AI 에이전트를 2세션 × 각 6~8체로 병렬 구동하여, 회사의 웹 도구 진열대를 하루 만에 29개에서 100개로 늘렸습니다.

병렬화 과정에서 품질이 떨어지는 원인은 에이전트의 능력 자체보다 '지시문 작성 방식'과 '결과물 수용 방식'의 설계에 있었습니다.

본 기사에서는 그날 버그를 4건 발견한 과정을 통해, 효과적이었던 조건과 빠뜨렸던 함정들을 절차 형태로 정리합니다.

• 작업 내용: 브라우저에서 작동하는 작은 웹 도구(소비세 계산・근무 시간 계산・직인 생성・PDF 처리 등)를 하나씩 추가하기
• 체제: 부모 세션 1개에서 서브 에이전트를 구동하고, 1체당 1도구를 할당하기
• 규모: 2세션 × 각 6~8체를 병렬 실행
• 구성: 각 도구는 <도구명>/app.js에 본체가 있고, 대장(JSON)・목록 페이지(HTML)・공통 CSS를 모든 도구가 공유하고 있음 - 검사: 공개 목록과 도구별 합격 조건을 정리한 검사표와 출력물을 대조하여 확인하기

결과는 29개→100개. 발견된 버그는 4건, 에이전트가 지적한 '지시 자체의 오류'가 2건이었습니다.

가장 효과적이었던 것은 절차 1입니다. 단순히 '구현해라'만 전달하면, 에이전트는 '작동했다'는 시점에서 멈춥니다. 검사 내용을 구체적으로 작성해야 비로소 결함이 드러납니다.

나쁜 예:
소비세 도구를 만들어라. 검증한 후에 끝내기
좋은 예:
...

좋은 예의 지시문으로 실제로 버그가 발생했습니다(후술할 '발생한 일' 1).

'왜 그 구현을 했는지'를 보고서에 작성하게 하니, 근거를 쓸 수 없는 판단이 본인에게 노출됩니다. 실제로 돌아온 근거는 다음 3가지입니다.

• 직인의 두 글자를 위아래로 쌓은 이유: '2열일 경우 '야마다'가 왼쪽부터 읽혀 '타야마다'처럼 보여 오해를 일으킨다'
• 서체 모양을 프레임에 맞출 때, 가로세로 비율 왜곡에 상한선을 둔 이유: '상한선이 없으면 '一'가 프레임 가득 막대로 변한다'(실제로 '一'로 검품한 후의 보고)
• 확대된 이미지가 약간 흐릿해지는 것을, 지시받지 않은 상태에서 FAQ에 작성하고 있었다

가장 질 높은 보고는 '지시된 사양에 무리가 있어 구현하지 않고 보고합니다'였습니다. 이후 프롬프트에 다음 문장을 추가했습니다.

지시된 사양에 무리가 있다고 판단되면, 구현하지 않고 근거를 첨부하여 보고할 것.
지시대로 만들다가 망가지는 것보다, 멈추고 보고하는 것이 더 가치가 있다

병렬화의 필수 조건입니다. 여러 에이전트에게 같은 파일을 건드리게 하면 망가집니다. 분담은 다음 표와 같이 했습니다.

대장에 넣을 JSON, 목록 페이지의 HTML, 한 줄 설명 같은 등록 정보는 서브 에이전트가 반환값으로 보내면, 부모가 붙여넣습니다.

프롬프트에 '검사 조건'란을 마련하고, 구현한 에이전트 스스로에게 채우게 합니다. DOM 구조 역시 어떤 전처리 과정을 거치지 않으면 저장할 수 없는지는 작성한 본인이 가장 잘 알고 있기 때문입니다.

절차 1~5를 정리한 프롬프트의 골격은 다음과 같습니다.

## 담당
<도구명>/app.js만 수정한다. 대장・목록 페이지・공통 CSS는 건드리지 않는다
## 검사
...

부모는 반올림만으로 계산하여 통과시켰습니다. 버림을 지정받은 에이전트가 다음 값을 근거로 보고했습니다.

110 / 1.1
// 99.99999999999999 → 버림으로 99원

반올림으로는 오차가 흡수되어 표에 나타나지 않는 버그였습니다.

근무 시간 도구에서 '심야대와 겹치는 부분부터 휴식을 통째로 제외한다'고 지시하자, 에이전트로부터 다음 반론이 돌아왔습니다.

해 그 규칙은 주간 근무에서 망가진다. 9:00~23:00・휴식 60분일 경우 심야 중첩 시간이 1시간밖에 안 되므로, 휴식 60분을 통째로 제외하면 심야 0분이 된다(낮에 쉰 휴식으로 심야 수당이 사라진다).

반론대로였기 때문에, 비례 배분 방식으로 변경했습니다. 지시의 오류로 돌아온 또 다른 건은 base64의 증가율이었습니다. 둘 다 숫자를 근거로 돌아왔습니다.

부모가 DOM을 보고 작성한 검사 조건은 5번 틀렸습니다.

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

위 5건 모두 '구현은 정상인데 검사가 실패하는' 형태로, 구현상의 버그는 단 한 건도 없었습니다.

출력 검사에서 3건에 대해 '저장된 파일이 떨어지지 않는다'고 나왔습니다. 보고하기 전에 실제 기기에서 재현을 시도하자, 3건 모두 정상적으로 작동하고 있었으며 화면에는 다음 안내가 표시되었습니다.

순서가 원래 그대로입니다. 페이지를 바꿔서 저장해 주세요
추출할 페이지를 선택해 주세요

검사 측에서 전처리 과정(선택/재배열)을 작성하지 않았을 뿐이었습니다. 반면, 같은 진입점에서 조사한 다른 툴에서는 실제 버그(비율 고정이 이미지 끝에서 깨지는 현상)가 발견되었습니다. 오탐지가 5번 연속된 후에야 진짜 버그가 나온 경우였습니다.

PDF 복구 툴은 지시대로 만들면 '복구할 수 없습니다'만 반환하는 툴이 될 수 있다는 것을 실측으로 알게 되었습니다. 에러는 발생하지 않고 화면도 정상적으로 작동하기 때문에, 검사는 모두 통과합니다. 구현한 에이전트가 실제 PDF로 테스트해보고서야 비로소 밝혀졌습니다.

완료 알림에 보고 본문이 담기지 않는 경우가 있었습니다. transcript에는 전문이 남아있지만, 단순하게 '마지막 발언'만 가져오면 실패합니다. 추가 질문을 한 에이전트의 경우, 마지막 발언이 '삭제할 부분 없음'과 같은 짧은 답변이었기 때문입니다.

툴을 추가하는 측과 검사표를 가진 측이 분리되어 있으면, 등록을 잊은 툴이 '판정 없음'으로 지나갑니다. 에러도 경고도 발생하지 않아, 검사를 통과한 것처럼 보입니다.

실제로 69개 중 20개가 미검사 상태로 공개되고 있었습니다. '44건 기록에 대해 공개 61건'이라는 다른 경고도 있었지만, 건수 차이만 보고 있기 때문에 등록 누락은 이쪽도 빠져나갔습니다.

부모(Parent)가 등록할 때 막은 것은 2건입니다.

• 참조 구현에서 카테고리를 잘못 복사한 경우 (TXT 툴인데 excel)
• 'PDF 내 글자를 선택할 수 없음'이 FAQ에서 빠져있던 경우. app.js의 시작 주석에는 'FAQ에 명기'라고 되어 있는데, 본문에는 들어있지 않았습니다.

'함정(落ちとし穴)' 3·4에 대한 대처로 운영 규칙을 다음 두 줄로 변경했습니다.

1. 검사 NG는 먼저 검사 측(전처리 과정・ID・준비 조건・합격선)을 의심한다
2. 다만 실제 버그가 섞여 있으므로, 사람에게 보고하기 전에 반드시 실제 기기에서 재현을 한다

의심하는 것과 확인하지 않는 것은 다릅니다. 검사 결과를 그대로 '버그 발견'으로 남에게 던지면, 상대방의 시간을 빼앗는 것은 물론이고 다음부터 검사 결과를 신뢰받지 못하게 됩니다.

transcript에서 보고 내용을 가져오는 규칙을 다음과 같이 변경했습니다.

등록 정보가 포함된 발언을 우선하여 채택한다.
없으면, 가장 긴 발언을 채택한다.

회수율은 7/9에서 9/9로 높아졌습니다.

'주의할 점(気をつける)'만으로는 등록 누락을 막을 수 없습니다. 공개 목록과 검사표를 대조하여, 판정 조건이 없는 툴을 지목하는 시스템을 도입했습니다. 이 시스템을 넣은 당일에, 자신이 추가한 4건을 그 시스템으로 포착했습니다.

탐지기는, 탐지할 수 있다는 것을 확인해봐야 비로소 탐지기가 됩니다. 일부러 1건 빼서 경고가 뜨는 것, 다시 넣으면 경고가 사라지는 것까지 확인했습니다.

못하는 것을 빠뜨리는 것은 이용자가 사용한 후에 깨닫게 되는 형태로, 가장 나쁜 결과입니다. FAQ 누락과 카테고리 잘못 복사는 등록 시 부모가 산출물을 그대로 넣지 않고 읽어봄으로써 막았습니다.

그날 발견된 버그 중 2건은 서브 에이전트 발(發)이었으며, 둘 다 지시하지 않은 발견이었습니다.

• KPI 측정의 이중 계상 (공통 함수가 내부에서 이벤트를 발생시키는데, 호출하는 쪽에서도 이벤트를 발생시키고 있었음)
• 소비세 1엔 차이

작업자가 늘어나면, '예전부터 그렇게 적혀 있으니 맞겠지'라는 것이 통하지 않는 눈이 많아집니다. 기존 코드를 새로운 눈으로 다시 읽어보는 기회로서, 병렬화의 효과에 포함해도 좋다고 생각합니다.

• '검증한 후에 끝내는 것'이 아니라, 구체적인 입력과 보고해야 할 출력값을 프롬프트에 작성한다.
• 판단 근거와 '사양에 무리가 있다면 멈추고 보고'를 프롬프트에 넣으면, 지시의 오류까지 반환된다.
• 서브 에이전트는 자신의 app.js만 건드리고, 공유 파일은 부모가 순차적으로 업데이트한다 - 검사 조건은 구현한 본인에게 작성하게 하고, 검사의 NG는 검사 측을 먼저 의심하면서 매번 실기에서 확인한다.
• 검사표 등록 누락은 차이점을 기계로 가져와서, 검출기 자체도 일부러 하나 빼서 동작을 확인한다.