dots에 개발 요청을 연쇄시키는 지시서와 CI 및 독립 검토의 실제 사례

이 글 자체도 dots가 작성했습니다. 사실 정리, 독립 검수, 공개는 현 담당자가 맡았습니다.

AI 에이전트에게 여러 공정을 맡길 때는 이번에 '공통된 합의를 먼저 문서화하기', '처음에 한 번 승인받기', '검증은 PR의 CI에서 진행하기'라는 틀을 사용했습니다. 게다가, CI 성공 후 독립 검토 과정에서 중대한 문제가 발견되었기 때문에, 마지막으로 다른 제품의 AI가 모든 줄을 읽는 공정을 추가하게 되었습니다.

이전 글인 'ChatGPT와 Claude를 통해 Slack 경유로 dots에 지시를 내리는 메커니즘'의 속편입니다. 프로젝트 번호와 GitHub의 고정 커밋(fixed commit) 지시서를 사용하고, PROGRESS.md를 현판으로 삼아 Slack 같은 대화방에서 접수와 보고를 연결합니다. 독립 검토부터 현 담당자의 검수까지 포함하여 요청을 처리하는 메커니즘을 실제 기능 개발에 적용했습니다.

대상은 재구축 중인 Deskly에 올릴 'AI 요청 대장'입니다. Deskly는 연락 및 프로젝트 대장 앱이며, 이번 기능은 사람과 AI 에이전트에게의 요청을 같은 번호로 접수부터 사람이 수령할 때까지 추적합니다.

Deskly 재구축의 핵심 코드와 동일한 코드를 사용하여 개인용, 회사용 등 요청을 관리하는 조직 단위인 '존(zone)'별로 별도의 인스턴스로 구동하는 방침입니다. 구현은 비공개 작업용 repo에서 진행했습니다.

완료된 범위는 메모리 저장 시제품, 상태 표시 컴포넌트, 현판 생성입니다. DB 저장, 기계용 인증, HTTP와 MCP, 배포는 포함되어 있지 않습니다. 이 글에서는 기능의 전체 사양보다는 요청과 검증의 구성 방식에 대해 다룹니다.

처음에 있던 현판용 Git repo를 대장으로 삼자는 안은 채택하지 않았습니다. 소유자가 검토 시트에서 논점을 선택하고, 공통된 합의를 문서화하여 비공개 현판 repo에 고정 커밋으로 두었습니다.

여기서 정한 주요 경계는 다음과 같습니다.

• 원본(正本)은 존별 관리 서비스에 둡니다.
• 번호는 입구에서 #<존 표시>-YYYYMMDD-NNN 형식으로 부여합니다. 일본 시간의 접수일과 일별 연속 번호를 사용하며, 999 다음은 1000이고 재사용하지 않습니다. - 작업 상태와 전송 상태는 별도로 관리합니다.
• 보냈는지 여부가 불분명할 때는 자동으로 다시 보내지 않습니다.
• 본인과 각자가 가진 bot을 분리하고, bot은 여러 에이전트가 공유합니다.

작업 상태는 '등록됨'에서 '담당자 결정', '착수 접수됨', '작업 중', '제출됨', '검토됨', '완료'로 진행됩니다. 전송 측면은 '전송 대기', '전송 중', '전송 완료/불명/실패'입니다. 검토에서는 이 상태의 경계가 문서대로 되어 있는지 확인하는 것으로 정했습니다.

같은 bot을 사용하는 에이전트는 branch의 최상단, 커밋 끝에 Agent: <이름> 및 PR 라벨로 구분합니다. 표시는 작업자를 식별하기 위한 것이며, 허가를 받는 데 사용하지 않습니다. 지시서에서도 작업자의 표시와 허용 범위는 분리하여 다룹니다.

이 명의 형태에는 GitHub 측의 제약도 있습니다. 무료 개인 계정에 더해 가질 수 있는 무료 machine account가 1개까지라는 규정 때문에, 에이전트별로 전용 계정을 만드는 방식은 취할 수 없다고 판단했습니다. (GitHub Terms of Service B. Account Terms)

또한, 개인 계정의 repo collaborator에게는 읽기 권한만 줄 수 있기 때문에, 현판 repo에 프로젝트 내용을 두지 않기로 했습니다. (개인 계정의 repo의 권한)

dots에 대한 요청 번호는 4가지로 나누었습니다.

• 설계만 진행. 코드는 작성하지 않음
• 시제품의 4단계 공정을 연쇄적으로 진행
• 상태 표시와 현판을 생성함
• 검토 지적 사항을 수정함

설계 단계에서는 기존 접수 방식인 case 메커니즘을 읽고, '저장과 거래의 기반은 재사용하고, AI 요청은 전용 표와 번호 매기기를 사용한다'는 안과 결정해야 할 논점을 돌려받았습니다. 소유자는 권장하는 대로 결정했습니다.

당초에는 다음 담당자에게 보낼 때마다 본인이 확인하던 합의였으나, 소유자의 의향으로 중간 확인을 없앴습니다. 처음에 절차/담당자/범위/중단 조건만 승인하면 그 안에서는 자동으로 진행됩니다. 사람이 개입하는 것은 마지막 수령과 멈췄을 때입니다.

이번 틀을 사용한다면, 다음 항목들을 한데 모읍니다.

• 참조할 공통 합의와 그 고정 커밋
• 요청 번호, 성과물, 작업 범위
• 공정 순서, 구현 및 검토 담당자
• 도중에 멈춰 사람에게 돌려줄 조건
• 검증 장소와 다음 공정으로 진행할 조건
• branch, commit, PR에 붙일 작업자의 표시
• 접수/진행 상황/최종 보고를 추적하는 장소

'처음에 한 번의 승인'은 이후 작업을 무조건 맡긴다는 의미가 아닙니다. 승인한 절차와 범위 안에서 자동으로 진행되다가, 조건에 맞으면 멈추는 형태입니다. 실제로 이번 시제품은 실행 환경의 전제가 맞지 않아 공정 0에서 한 번 멈춘 적이 있습니다.

그림 속의 작은 글씨는 이미지를 확대하여 확인할 수 있습니다. 요점은 본문에도 작성되어 있습니다.

이번 그림은 이번 학습 내용을 포함한 다음 유형입니다. 다른 제품의 AI를 이용한 전체 라인 리뷰를 미리 배치했지만, 이번 첫 번째 전체 라인 리뷰는 최초 가져오기 이후에 진행되었습니다.

처음 지시에서는 모든 공정에서 로컬 테스트가 필수였습니다. 하지만 dots 작업 환경에서 의존성을 가져올 수 없어 pnpm test가 실패했습니다. 의존성 확인 통신 역시 자동 승인 취소로 인해 통과하지 못했습니다.

dots는 멈추는 조건에 따라 중단했고, 회피나 재시도는 하지 않았습니다. 이 부분은 지시가 작업 환경에 적절하지 않았던 점입니다. '검증은 PR의 CI에서 한다'라는 추가 지시 한 장만으로 재개되었고, 공정 4까지 막힘없이 진행되었습니다.

각 공정에서는 구현과는 다른 담당자가 리뷰를 했으며, CI 5종의 성공을 확인한 후에 다음 단계로 넘어갔습니다. core 테스트는 상황 표시까지 346건에서 580건으로 증가했습니다.

요청 사항에는 '테스트한다'뿐만 아니라 어디서 검증할지 작성합니다. 이번에는 PR의 CI를 검증 장소로 삼아, dots 작업 환경에 의존성 가져오기를 요청하는 지시를 수정했습니다. 중단을 우회하지 않고, 지시의 전제를 바로잡아 재개할 수 있었던 점은 그대로 활용 가능한 유형이었습니다.

최초 가져오기 이후, 로컬 Claude가 5개의 서브 에이전트로 분담하여 전체 라인을 읽었습니다. dots는 OpenAI의 상시 작동 에이전트이고, Claude는 Anthropic의 제품입니다. 다른 제품을 사용하는 이유는 놓치는 부분이 중복되는 검토를 추가하기 위함입니다.

CI 테스트 580건이 모두 성공하고, dots 내부 리뷰도 지적 사항이 없었던 상태에서, 심각(Major) 1건, 보통(Medium) 12건, 경미(Minor) 약 20건, 테스트 이름과 assert의 불일치 약 20건을 발견했습니다.

심각한 문제는 다음 순서로 이중 전송에 이르는 경로입니다.

• 요청은 전송 중이지만, 수신자 기록에는 아직 나타나지 않음
• 그것만을 근거로 실패로 변경할 수 있음
• 실패 1회차에서는 연쇄가 멈추지 않아, 다른 Idempotency Key로 다음 전송이 자동으로 생성됨
• 첫 번째 전송이 지연되어 도착하면, 이중 전송이 발생함

'불명확하면 자동 재전송하지 않는다'고 결정했더라도, 그 앞 단계에서 쉽게 실패로 전환할 수 있다면 다른 전송이 만들어집니다. 문서의 조건을 상태 전이와 다음 작업까지 연결하여 읽을 필요가 있었습니다.

내부 지적 사항 중에는 공정을 진행할 때마다 사람의 정지 확인이 필요해서 중간 자동 진행이 불가능한 경우, 작업 담당자가 보고 ID를 선점하여 사람의 수령을 실패하게 만들 수 있는 경우, 설정 변경으로 인해 기록(record)을 가져올 수 없게 되는 경우가 있었습니다. 구현과 테스트가 갖춰져 있어도, 약속과의 차이는 남아있었습니다.

테스트의 취약점은 다른 요청에서도 점검에 사용할 수 있도록 정리되었습니다.

기대하는 오류 종류를 보지 않고, '거부됨'이라는 것만 확인하는 테스트가 있었습니다. 대상 검사를 삭제해도 통과하는 상태입니다. 이름이 특정 검사를 주장한다면, 그 검사에 의한 거부임을 assert로 확인할 수 있는지 읽어봅니다.

'동시 100건'이라는 이름의 테스트가 실제로는 1건씩 순차적으로 처리하고 있었습니다. 건수만 봐서는 동시 실행 확인이 되지 않습니다. 테스트 내에서 처리를 어떤 순서로 시작하는지까지 읽고, 이름의 조건과 일치하는지 확인합니다.

호출되지 않는 함수의 호출 횟수가 0임을 확인하는 테스트도 있었습니다. 0이라는 결과뿐 아니라, 검증하고 싶은 처리와 확인하는 함수가 연결되어 있는지 여부가 점검 대상이 됩니다.

dots 내부 리뷰는 같은 제품의 다른 담당자였습니다. 약속에서는 제품명이 다르다는 것만으로는 독립적인 리뷰로 간주하지 않는다고 했습니다. 이번에 알게 된 것은 그 반대편에서, 같은 제품의 다른 담당자도 같은 놓침을 했다는 것입니다. 담당자를 분리했다는 기록 외에, 마지막으로 다른 제품의 AI가 전체 라인을 읽는 공정을 배치하는 것이 이번 학습입니다.

지적 사항을 R-01R-13으로 정리하고, 장소와 수정 방법 요건을 작성한 수정 요청을 1회 승인으로 전달했습니다. dots는 약 3시간 만에 공정 04를 마치고, 테스트는 718건이 되었습니다.

Slack의 마지막 보고가 오지 않아 같은 스레드에서 상황을 문의하자, R-01~R-13 각각의 수정 위치와 테스트 이름이 돌아왔습니다. 그 후, 로컬 AI가 3개의 서브 에이전트로 다시 읽고 있습니다.

결과는 심각 0건으로, 이중 전송 경로는 막혔습니다. 새로운 내부 지적 사항은 2건입니다.

• 복원 검사를 완화했을 때, 기계 역할 대조까지 빠짐
• 풀리지 않는 '불명'을 사람이 실패로 결정할 출구가 없음

이 2건은 다음 공정의 시작에서 고치기로 하고, 소유자의 승인으로 로컬에 가져왔습니다. dots에는 병합(merge)시키지 않았습니다. 수정된 지적 사항과 새롭게 남은 지적 사항을 나누어 수용하는 판단입니다.

먼저 합의 사항을 확정하면, 구현 요청과 검토 모두 동일한 문서를 참조할 수 있습니다. 최초 승인에는 공정(工程), 담당자, 범위, 중단 조건 등을 포함하고, 검증은 PR의 CI에 맡깁니다. 마지막으로는 다른 제품의 AI가 모든 줄을 읽고 테스트 이름 및 assert를 대조하며, 수정 후에도 다시 한번 읽어봅니다.

아직 실제 저장, 인증, 배포(配備), 구역 표시, 사본 보관 장소와 간격은 미정입니다. 시제품 수령과 향후 구현 범위를 분리하여 다음 단계로 진행합니다.

이전 작업 요청의 시작점에 이번 연쇄 및 검증의 양식을 담았습니다. 중간 과정을 맡길 조건을 먼저 작성하고, 마지막에 무엇을 읽고 승인할지까지 개발 절차에 포함하는 형태입니다.

※ 헤더 이미지와 인포그래픽 그림은 AI(이미지 생성)로 제작했습니다.

※ 본문 삽화도 AI(이미지 생성)로 제작했습니다.

작성자: ishizakahiroshi

군마 북부에서 보호묘 2마리와 함께 사는 재택 엔지니어(만물상)

X (업무 위탁/각종 상담 문의):

백엔드, 인프라, AI 연계 관련 업무 위탁을 받고 있습니다. 풀 리모트입니다. 스팟이나 주 2~3시간부터도 환영하며, 다양한 프로젝트에 참여할 수 있다면 좋겠습니다. 다음과 같은 상담도 환영합니다.