Android 서브에이전트 워크플로 — 스킬 프로젝트 소개

역할이 바뀌어도 남아 있어야 하는 판단

Android 서브에이전트 워크플로에서는 담당이 바뀌어도 앞에서 정한 범위와 남은 문제를 알 수 있어야 했습니다. 요구사항 검토, 코드 품질 가이드, 구현, 리뷰를 맡은 담당들이 결정한 내용을 문서로 전달하도록 했습니다. 이전 대화를 전부 읽지 않아도 다음 작업을 시작할 수 있게 하려는 선택이었습니다.

그래서 공통 세션 문서와 단계별 인수인계 문서를 만들었습니다. 세션에는 현재 단계와 실행 모드, 이전 전달 문서와 최신 전달 문서, 포함할 범위와 제외할 범위를 남깁니다. 각 담당은 판단 요약과 근거 위치, 다음 담당이 반드시 할 일을 작성하도록 했습니다.

여기서 인수인계는 긴 작업 후기를 남기는 일이 아닙니다. 다음 담당이 어느 조건에서 시작해야 하는지 확인할 수 있어야 합니다. 문서를 많이 만들더라도 대상 경로와 미해결 문제가 연결되지 않으면 같은 판단을 처음부터 다시 해야 합니다.

다음 담당을 부르는 책임은 한곳에 두었습니다

각 담당이 작업을 끝내고 임의로 다음 역할을 호출하게 하지 않았습니다. 지휘 역할이 최신 전달 문서를 읽고 문서 검토, 가이드 작성, 구현, 리뷰 중 다음 하나를 결정하도록 했습니다. 새 실행에는 요구사항과 기술 설계 문서가 있는지 먼저 확인합니다.

이미 세션이 있다면 마지막으로 전달된 상태에서 다시 시작합니다. 리뷰가 반려됐다면 무조건 첫 단계로 돌아가지 않고 구현과 리뷰 사이의 필요한 수정으로 이어집니다. 승인이나 우려를 남긴 완료 결과라면 종료할 수 있도록 했습니다.

문서 기반으로 작업하는 앞의 두 역할은 격리된 맥락으로, 구현과 리뷰는 같은 대화의 작업 맥락을 이어 쓰는 방식으로 설계했습니다. 어느 쪽이든 함께 지킬 규칙은 세션 문서와 인수인계 문서에 남깁니다. 대화가 연결돼 있다는 사실만으로 전달을 마쳤다고 보지는 않았습니다.

반려 후 돌아오는 순서를 검사할 수 있어야 했습니다

2026년 3월 27일에는 순서 검사에서 실제 계약과 맞지 않는 부분을 수정했습니다. 이전 검사는 문서 검토, 가이드 작성, 구현, 리뷰가 딱 한 번씩 등장하는 순서만 허용했습니다. 리뷰가 반려돼 구현과 리뷰를 다시 거치면 정상적인 재진입도 순서 불일치로 잡히는 구조였습니다.

저는 기본 순서 뒤에 구현과 리뷰의 반복 쌍을 허용하도록 바꿨습니다. 검증기에 최대 세 번의 추가 반복 패턴을 넣었습니다. 순서를 아무렇게나 허용한 것이 아니라, 처음 단계를 유지하면서 특정 두 단계가 다시 이어지는 경우를 인정한 것입니다.

이 수정에서 중요했던 것은 계획에 반복을 적는 것과 검증기가 그 반복을 받아들이는 일을 함께 맞추는 것이었습니다. 운영 절차는 재시도를 허용하는데 검사기는 단일 통과만 요구하면 담당이 규칙을 지켜도 실패하게 됩니다. 리뷰 루프의 종료 조건과 허용되는 단계 이력이 같은 구조를 설명해야 했습니다.

모든 미완료를 같은 반려 사유로 두지 않기

리뷰에서는 네 종류의 문제를 구분했습니다. 문맥 전달이 끊긴 문제, 현재 범위 안에서 해결해야 할 결함, 의도적으로 남긴 공백, 후속 개선입니다. 앞의 두 종류는 다음 수정에서 해결해야 하지만, 뒤의 두 종류를 자동으로 필수 수정에 올리지는 않습니다.

실제 Android 제품을 완성하는 모드와 스킬 전달 체인을 검증하는 모드도 나눴습니다. 제품 모드에서는 요구 범위의 구현과 품질이 목표입니다. 전달 체인 검증에서는 세션이 이어지고 대표 구현 경로와 검수 자료가 연결되는지가 먼저입니다.

예를 들어 전달 체인 검증에서 일부 기능을 의도적으로 제외했다고 명시했다면, 전체 제품 기능이 없다는 이유만으로 끝없이 반려하지 않습니다. 반대로 현재 범위에 포함된 결함이라면 제외 설명으로 넘어갈 수 없습니다. 같은 지적도 실행 목표와 범위에 따라 판단해야 한다는 기준을 남겼습니다.

사람의 설명과 파서의 필드는 다르게 다루기

인수인계 문서는 사람이 읽으면서 도구도 확인합니다. 저는 파서가 읽는 필드 이름을 소문자와 밑줄 형식으로 고정했습니다. 친절한 한국어 설명은 값이나 본문에 쓰되, 식별자 자체를 담당마다 다르게 바꾸지 않도록 했습니다.

세션 업데이트도 일정한 제목 형식으로 누적합니다. 기존 세션을 덮어쓰면 이전 리뷰가 무엇을 요구했는지 찾기 어려워지므로 append 방식으로 남깁니다. 선택적인 맥락 스냅샷이 있더라도 필수 판단은 세션과 전달 문서에서 찾을 수 있어야 합니다.

격리된 역할이 돌아온 뒤에는 필수 필드가 있는지 확인하고, 지휘 역할이 이미 알고 있는 세션 값이 빠졌다면 보정하도록 했습니다. 전달 문서가 존재하는 것과 다음 작업에 필요한 정보를 갖췄다는 것은 다르기 때문입니다. 새 역할을 시작하기 전에 이 경계를 확인합니다.

로컬 검증과 앱 품질 검증을 구분했습니다

3월 31일에는 로컬 자체 검증 대상의 의미를 더 분명히 했습니다. 검증용 폴더는 사용자가 만드는 로컬 대상이며 저장소에 포함된 Android 샘플 앱으로 설명하지 않도록 정리했습니다. 이 프로젝트 자체도 앱 기능을 제공하는 대신 역할 계약을 다룹니다.

작은 검증 하네스는 문서 존재와 필수 필드, 세션 체인, 역할 순서를 확인합니다. 근거 파일이 있다는 사실을 검사하는 것과 그 안의 빌드 결과가 정확한지, 앱 동작이 좋은지 확인하는 것은 별개의 검수입니다. 전달 계약을 통과했다고 제품 품질 전체가 검증된 것처럼 설명하지 않습니다.

이 작업에서 남긴 개발 기준은 다음 담당이 같은 목표를 이어받을 수 있는지입니다. 현재 범위와 미해결 문제, 다시 확인할 근거가 문서에 있어야 하고, 재진입 순서도 검증기가 받아들여야 합니다. 역할을 추가하는 것보다 역할 사이에서 판단을 잃지 않는 조건을 먼저 만들었습니다.