여러 공정을 맡기는 개발 방식: 규칙 설정과 단일 승인, 독립 검토

본 기사 자체도 dots가 작성했습니다. 사실 정리 및 독립 검수, 공개는 담당자가 진행합니다.

이전 글인 'ChatGPT와 Claude를 통해 Slack으로 dots에 지시를 내리는 메커니즘'에서는 AI에게 요청을 전달하고 결과를 받는 입구를 만들었습니다. 프로젝트 번호를 부여하고 GitHub의 고정 커밋에 지시서를 배치하며, 진행 상황은 대시보드의 PROGRESS.md로 추적합니다. Slack의 동일한 대화에서 접수와 보고를 연결하여 독립 검토 및 담당자의 검수를 거쳐 받아들이는 메커니즘입니다.

이번에는 그 메커니즘을 사용하여 재작업 중인 Deskly에 넣을 기능을 개발했습니다. 여러 공정을 첫 번째 승인으로 맡기려면 무엇을 결정해야 하는지, CI가 성공한 후에 무엇을 봐야 하는지를 실제 순서대로 정리합니다.

dotsに機能開発を任せる。取り決め、1回の承認、別のAIのレビューを組み合わせる

取り決めを先に書く、1回の承認で連鎖させる、別のAIがレビューする、直して読み直して取り込むという4手順

주제는 AI 요청의 대장(台帳) 시제품 제작

Deskly는 연락과 프로젝트를 관리하는 대장 앱으로, 현재 재작업 중입니다. 이번에 만든 것은 사람과 AI 에이전트에게 요청을 동일한 번호로 접수하고, 사람이 수령할 때까지 추적하는 'AI 요청의 대장'입니다.

작업은 비공개 작업용 repo에서 진행했습니다. 완성된 것은 메모리 저장 시제품, 상황 표시 컴포넌트, 대시보드 생성까지입니다. DB 저장, 기계용 인증, HTTP와 MCP, 배치는 앞으로 할 일입니다.

이 개발 과정에서는 작업의 연속성을 어디까지 자동화하고, 어디서 사람에게 되돌릴지라는 규칙 설정도 다루었습니다.

코드를 작성하기 전에 공통 규칙을 고정하기

처음에는 대시보드용 Git repo를 대장으로 하는 안이 Draft PR로 나왔습니다. 그 안은 채택하지 않았고, 검토 시트에서 소유자가 논점을 선택하여 공통의 규칙을 문서화했습니다. 이 문서는 비공개 대시보드 repo에 고정 커밋으로 배치했습니다.

나중에 각 요청마다 같은 설명을 반복할 필요 없이 이 문서를 참조할 수 있습니다. 리뷰에서도 구현이 무엇을 따라야 했는지 추적할 수 있게 됩니다.

정본과 번호를 결정하기

대장의 정본은 존(zone)별 관리 서비스로 했습니다. 존이란 개인용, 회사용 등 요청을 관리하는 조직의 단위를 말합니다. Deskly 재작업의 핵심과 같은 코드를 사용하며, 존별로 다른 인스턴스로 작동할 방침입니다.

번호는 입구에서 부여합니다. 형식은 #<존 표시>-YYYYMMDD-NNN입니다.

일본 시간의 접수일과 일별 순번을 사용하여 재사용하지 않습니다. 999 다음은 1000입니다. 번호를 후속 공정에서 다시 붙이지 않고, 접수부터 사람의 수령까지 동일한 요청으로 추적하기 위한 기반을 마련했습니다.

작업 상태와 전송 상태를 분리하기

작업 상태는 등록됨, 담당자 결정, 착수 접수됨, 작업 중, 제출됨, 검토됨, 완료 순으로 진행됩니다. 반면, 전송 상태는 전송 대기, 전송 중, 전송됨/불명/실패로 별도로 관리합니다.

특히 정한 것은 보냈는지 여부가 불분명할 때 자동으로 재전송하지 않는 것입니다. 작업이 진행되었는지와 요청이 상대방에게 도착했는지를 각각 다른 판단으로 취급합니다. 나중에 리뷰에서 바로 전송 경계에서 중대한 문제가 발견되었습니다.

명의 표시와 권한을 분리하기

명의는 본인과 각 사람이 하나씩 가진 bot, 이렇게 2단계로 했습니다. 같은 bot을 여러 에이전트가 공유하며, branch의 헤드나 커밋 끝에 Agent: <이름>이라는 PR 라벨로 구분합니다. 이 표시는 작업자를 식별하기 위한 것이며, 승인에는 사용하지 않습니다.

GitHub 규정상 무료 개인 계정에 더해 가질 수 있는 무료 machine account는 1개까지이므로, 에이전트마다 전용 계정을 만드는 방식은 취할 수 없다고 판단했습니다. GitHub Terms of Service의 B. Account Terms

또한, 개인 계정 repo의 collaborator에게 읽기 전용 권한을 줄 수는 없습니다. 이 제약 때문에 대시보드 repo에 프로젝트 내용을 넣지 않기로 했습니다. 개인 계정 repo의 권한

승인은 처음에 한 번에 모아서, 멈추는 조건을 전달하기

당초 규칙은 다음 담당자에게 보낼 때마다 본인이 확인하는 형태였습니다. 도중에 소유자가 '매번 확인하고 싶지는 않다. 전부 처리하게 하고, 마지막에 문제가 있으면 보고해서 확인하는 형태가 좋다'로 방침을 바꿨습니다.

그래서 처음에 절차/담당자/범위/멈추는 조건을 승인하면, 그 안은 자동으로 진행되도록 수정했습니다. 사람이 보는 것은 마지막 수령과 멈췄을 때입니다. 맡길 범위와, 맡긴 채로 진행해서는 안 되는 경계를 동시에 전달합니다.

dots에 대한 요청 번호는 설계만, 시제품의 연속성, 상황 표시 및 대시보드 생성, 리뷰 지적 수정의 네 가지였습니다. 설계 요청에서는 코드를 작성하지 않고, 기존 접수처인 case의 메커니즘을 읽게 했습니다. '저장과 거래의 기반은 재사용하고, AI 요청은 전용 표와 번호를 붙인다'는 권고와, 결정해야 할 논점이 돌아왔고, 소유자는 권고대로 결정했습니다.

그 후에 전달한 연결의 형태를, 이번 배움을 더해서 그림으로 그리면 다음과 같습니다.

最初に人が承認し、工程0のDraft PRから工程1〜4を各工程のCIで進める。停止条件に当たれば人へ戻し、最後は別の製品のAIによる全行レビューを経て人が受け入れる

그림의 세부 글자는 이미지를 확대하여 확인할 수 있습니다. 요점은 본문에도 적혀 있습니다.

이 그림의 '가져오기 전에 다른 제품의 AI가 읽는다'는 것은 이번 경험을 통해 마지막에 추가하는 공정입니다. 이번에 다른 AI가 처음에 전체 행을 읽은 것은, 최초 가져오기 이후였습니다.

실행 환경과 검증 장소를 지시서로 분리하기

시제품의 연결은 공정 0에서 멈췄습니다. dots의 작업 환경에서 의존성을 얻지 못했고, pnpm test가 실패했기 때문입니다. 의존성 확인 통신도, 자동 승인 취소로 인해 지나가지 않았습니다. dots는 멈출 조건에 따라 회피나 재시도를 하지 않고 멈췄습니다.

이 정지의 원인은 지시 측에 있었습니다. 모든 공정에서 수동 테스트를 필수화했기 때문에, 작업 환경이 그 조건을 충족할 수 없었습니다. '검증은 PR의 CI로 진행한다'는 추가 지시 한 장을 전달하자 재개되었고, 공정 4까지 멈추지 않고 진행했습니다.

각 공정에서는 구현과는 다른 담당자가 리뷰하고, CI 5종의 성공을 확인한 후에 다음으로 넘어갔습니다. 상황 표시까지 포함하면, core 테스트는 346건에서 580건으로 늘어났습니다.

여기서 가져가야 할 형태는, 검증 장소까지 요청에 적는 것입니다. 의존성을 얻지 못할 때가 있는 작업 환경에서 매번 수동 테스트를 필수화하면, 공정의 연결을 시작할 수 없습니다. 이번에는 PR의 CI를 검증 장소로 맞추었습니다.

CI 성공 후에 다른 제품의 AI가 전체 행을 읽기

최초 가져오기 이후, 수동 Claude가 5개의 서브 에이전트로 분담하여 전체 행을 읽었습니다. dots는 OpenAI의 상시 가동 에이전트이고, Claude는 Anthropic의 제품입니다. 제품의 우열을 비교하기 위함이 아니라, 놓치는 부분이 중첩되기 어렵게 재검토를 넣기 위함입니다.

作業役が工程を進めた成果を、最後に別の目で全体から読み直す場面

그 시점에서 CI 테스트 580건은 모두 성공했고, dots 내부 리뷰도 지적 사항이 없었습니다. 그럼에도 불구하고, 심각한 문제 1건, 보통 12건, 경미 약 20건, 테스트명과 assert의 불일치 약 20건이 발견되었습니다.

심각한 문제는, 이중 전송으로 이어지는 경로였습니다. 전송 중인 요청을 '수신처의 기록에 아직 없다'는 이유만으로 실패시킬 수 있었고, 실패 1회차에서는 연결이 멈추지 않았습니다. 다른 Idempotency Key로 다음 전송이 자동으로 만들어지고, 첫 번째 전송이 늦게 도착하면 이중이 됩니다.

'불명확할 때는 자동으로 재전송하지 않는다'는 문서상의 합의와, 실패로 옮기는 구현 조건들을 나란히 읽어볼 필요가 있었습니다. CI에서 성공한 작업만 봐서는, 이 경로는 닫혀있지 않았습니다.

내부 지적 사항에는, 다음 공정으로 넘어갈 때마다 사람의 정지 확인이 필요하여 '도중에 자동'이라는 것이 성립하지 않는 점, 작업 담당자에 의한 보고 ID 선취로 사람의 수령을 실패하게 만들 수 있는 점, 설정을 조금 바꾸면 기록이 사라지게 되는 경우가 있었습니다.

테스트명과 assert를 대조하기

테스트에도, 의도와 실제 검사가 어긋난 것이 있었습니다.

기대하는 오류 종류를 확인하지 않고, '거부되었다'는 것만 보고 있다. 대상 검사를 지워도 통한다
'동시 100건'이라는 이름이라도, 실제로는 1건씩 순차적으로 처리하고 있다
호출되지 않는 함수의 호출 횟수가 0임을 확인하고 있다

独立レビューで見つかった重大1件、中12件、軽約20件と、テスト名とassertの食い違い約20件。拒否理由、同時実行、呼び出し対象に関する3つの弱さ

테스트 건수가 늘어나도, 이름이 주장하는 조건을 assert가 확인하는지는 별도로 읽어야 합니다. '그 검사를 지워도 통하지 않을까'라는 시각을 포함하여, 테스트 자체를 리뷰 대상에 둡니다.

dots 내부의 독립 리뷰는, 같은 제품의 다른 담당자에 의한 것이었습니다. 합의에서는, 제품명이 다르다는 것만으로는 독립 리뷰로 간주하지 않는다고 했습니다. 이번에 알게 된 것은 그 반대편으로, 같은 제품 안에서 담당자를 나누어 봐도 놓치는 부분이 있었습니다. 그래서 마지막에는 다른 제품의 AI로 전체 행을 다시 읽는 공정을 두기로 했습니다.

수정은 지적 사항별로 요구사항을 전달하고, 다시 읽기

지적 사항을 R-01~~R-13으로 정리하고, 장소와 고치는 방법의 요구사항을 적어, 수정도 1회의 승인으로 전달했습니다. dots는 약 3시간 만에 공정 0~~4를 끝냈고, 테스트는 718건이 되었습니다.

Slack으로의 마지막 보고는 도착하지 않았습니다. 같은 스레드에서 상황을 묻자, 각 지적 사항에 대해 수정한 장소와 테스트명이 돌아왔습니다. 구현을 마친 것과, 요청 대화로 보고가 돌아오는 것도, 마지막에 대조할 필요가 있었습니다.

수동 AI가 3개의 서브 에이전트로 다시 읽은 결과, 심각한 것은 0건이었고, 이중 전송 경로는 닫혔습니다. 한편, 새로운 내부 지적 사항이 2건 있었습니다. 복원 검사를 완화하는 과정에서 기계의 역할 대조까지 빠진 것과, 풀 수 없는 '불명'을 사람이 실패로 결정할 출구가 없는 것입니다.

이 2건은 다음 공정 초반에 고치기로 하고 가져왔습니다. 가져오기는 소유자의 승인으로 수동이 진행했고, dots에는 merge시키지 않았습니다.

다음에 사용할 개발의 형태

이번 흐름을 다음에 사용한다면, 공통의 규정을 먼저 확정하고, 이를 참조하여 승인 절차・담당자・범위・중단 조건을 전달할 것입니다. 각 공정 검증은 PR의 CI(Continuous Integration)에 맡기고, 마지막에는 다른 제품의 AI가 모든 줄을 읽습니다. 지적 사항을 수정한 후에도 다시 읽어보고, 사람이 판단하는 문제를 받아들입니다.

실제 운영 환경에서의 저장・인증・배포, 영역 표시, 기록 보관 장소와 간격은 아직 정해지지 않았습니다. 시제품이 진행된 것과 실제 운영에 사용 가능한 것은 분리하여 다루고, 남은 논점도 다음 요청으로 넘기겠습니다.

요청의 진입점을 만든 이전 작업에서, 이번에는 그 진입점에서 여러 공정을 맡기는 단계까지 발전했습니다. 자동으로 진행할 범위를 문서화하고, 중단 조건과 마지막에 읽는 공정을 배치합니다. 이 조합이 다음 개발로 가져갈 형태입니다.

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

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

작성자: ishizakahiroshi

군마 북부에서 보호묘 2마리와 함께 사는 재택 엔지니어(만물상)
X(업무 위탁・각종 상담은 여기):

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