4편에서 AI가 행동할 권한 경계를 정했다. 다음으로 부딪힌 문제는 작업의 크기였다. 하나의 사용자 기능이 클라이언트, API, 외부 연동, 운영 화면처럼 여러 저장소를 지나가면 “전체를 분석해 줘”라는 요청은 너무 넓었다.
AI가 한 번에 많은 파일을 읽을 수 있어도 모든 내용을 같은 깊이로 판단하는 건 별개의 문제다. 탐색 로그와 빌드 결과가 쌓이면 정작 사용자가 승인한 목표가 대화 뒤로 밀렸다. 그래서 일을 작게 쪼개는 기준을 Git과 시스템 경계에서 찾았다.
파일 수가 아닌 책임으로 나눈 작업
처음에는 저장소마다 하나씩 나누면 충분하다고 생각했다. 그러나 공통 계약 파일이나 생성 코드는 여러 저장소에 영향을 줬고, UI와 API가 같은 파일을 기준으로 움직이기도 했다. 결국 작업 단위는 파일 개수가 아니라 한 가지 질문에 독립적으로 답할 수 있는 범위가 됐다.
예를 들어 결제 요청 하나의 흐름을 분석한다면 다음처럼 나눌 수 있다.
사용자 화면
-> 입력값과 표시 조건
내부 API
-> 거래 생성과 유효성 검사
외부 연동 계층
-> 서명, 요청, 응답 정규화
운영 화면
-> 조회, 상태 표시, 수동 처리
검증 경로
-> 테스트, 로그, DB 읽기, 실제 화면
각 작업은 결과물도 달라야 했다. “관련 코드를 봤다”가 아니라 UI는 화면 조건표, API는 요청과 응답 계약, 외부 연동은 상태 변환표, 검증은 증거 목록을 남기는 식이다.
Git으로 먼저 찾은 영향 범위
작업 분할 전에 현재 증상과 가까운 변경을 확인했다.
git log --oneline --decorate -- path/to/example
git show --stat <example-commit>
git diff <known-good>..<current> -- path/to/example
여기서 목적은 범인을 찾는 것이 아니라 변경의 경계를 찾는 것이었다. 한 커밋이 공통 모델과 클라이언트 화면을 같이 바꿨다면 두 영역은 독립 작업이 아니다. 반대로 같은 기능명이라도 서로 다른 저장소가 계약으로만 연결돼 있다면 분석은 나누고 계약 검토에서 다시 합칠 수 있다.
나는 분할 전에 아래 표를 만들었다.
| 작업 | 소유 범위 | 입력 | 결과 | 의존 관계 |
|---|---|---|---|---|
| UI 흐름 | 화면 컴포넌트 | API 응답 계약 | 표시 조건과 수정안 | API 계약 확정 후 구현 |
| API 흐름 | 라우터·서비스 | UI 요청, 내부 모델 | 호출 경로와 변경안 | 공통 모델과 연결 |
| 검증 | 테스트·로그 | 구현 커밋 | 통과·실패 증거 | 구현 이후 실행 |
이 표가 있으면 동시에 진행할 수 있는 일과 순서가 필요한 일이 보인다.
병렬화가 가능한 조건
여러 에이전트를 쓰면 항상 빨라질 것 같지만, 같은 파일을 만지면 결과를 합치는 비용이 커졌다. 내가 사용한 기준은 세 가지였다.
- 입력과 출력이 명확하게 정의돼 있는가
- 서로 다른 파일 또는 저장소를 소유하는가
- 한 작업의 결정이 다른 작업의 전제조건이 아닌가
셋 중 하나라도 아니면 순차 작업으로 남겼다. 특히 API 계약과 공통 모델은 여러 작업의 교차점이므로 먼저 한 곳에서 결정했다.
workstream: client-ui
owns:
- src/screens/example
reads:
- api-contract.md
must_not_edit:
- shared/models
deliverable:
- 화면 상태표
- 변경 후보 파일
- 확인하지 못한 조건
이런 작업 패킷은 에이전트에게 역할 이름만 붙이는 것보다 효과적이었다. “프런트엔드 전문가”보다 어떤 파일을 소유하고 무엇을 반환해야 하는지가 충돌을 줄였다.
OpenAI의 Codex 문서도 독립적인 코드 탐색이나 여러 단계의 기능 작업처럼 병렬성이 높은 문제에서 서브에이전트가 도움이 될 수 있다고 설명한다. 반대로 작업마다 모델과 도구 사용이 추가되므로, 작고 결합된 문제까지 억지로 나누면 비용만 늘어난다.
합치는 역할의 중요성
작업을 나눴다고 최종 판단까지 나눌 수는 없었다. 각각의 결과가 맞아도 서로 다른 전제를 사용했을 수 있기 때문이다. 그래서 한 작업은 항상 통합 역할로 남겼다.
각 작업 결과 수집
-> 공통 계약과 용어 비교
-> 겹치는 파일과 상충 결정 확인
-> 전체 호출 경로 재구성
-> 하나의 검증 계획으로 통합
예를 들어 UI 분석은 응답 필드가 항상 존재한다고 가정했는데 API 분석은 선택값이라고 확인할 수 있다. 이런 차이를 발견하지 못하면 두 결과를 단순히 붙여도 구현은 실패한다.
작업 분할과 문맥 오염
병렬 작업의 또 다른 장점은 속도보다 컨텍스트 관리였다. 광범위 검색 결과, 빌드 로그, 실패한 가설을 주 작업 대화에 모두 쌓지 않고, 각 작업에서 필요한 결론과 증거만 가져올 수 있었다.
다만 요약만 믿지는 않았다. 통합 전에 변경 파일과 핵심 증거를 다시 확인했다.
git diff --stat
git diff --check
git diff -- path/to/shared-contract
에이전트의 “완료” 보고는 검토를 시작할 신호이지 완료 증거가 아니었다.
내게 맞았던 분할 기준
여러 저장소를 다루면서 가장 안정적이었던 순서는 아래와 같았다.
사용자 흐름 확인
-> Git으로 영향 범위 확인
-> 저장소와 책임 경계로 작업 분할
-> 공통 계약을 먼저 결정
-> 독립 작업 진행
-> 변경과 증거를 한 곳에서 재검토
작업을 잘게 쪼개는 것 자체가 목표는 아니다. 독립적으로 검증 가능한 단위로 나누고, 다시 합칠 지점을 분명히 만드는 것이 목적이다. 이 기준이 생긴 뒤 AI는 “전체를 대충 아는 한 명”보다 “범위가 명확한 여러 작업자와 한 명의 통합자”에 가까워졌다.
이전 글: Codex AI 하네스 엔지니어링 설계 4 — 권한 통제
다음 글: Codex AI 하네스 엔지니어링 설계 6 — 검증 체계
참고: OpenAI Codex의 Subagents 안내
공식 문서 기반의 추가 정리
작업 당시에는 눈앞의 오류를 먼저 고쳤지만, 이후 기술 문서와 맞춰 보며 확인 순서를 조금 더 구체화했다.
에이전트 활용 자료를 다시 읽으며 workflow와 agent를 먼저 구분했다. 순서와 분기가 정해진 일은 workflow로 고정하고, 탐색이 필요한 부분만 도구 선택을 맡기는 편이 결과를 비교하기 쉽다. 저장소 작업도 격리된 환경, 명시적 권한, 실행한 테스트와 diff가 함께 있어야 검토 가능한 변경이 된다.
하네스는 지시문 모음보다 입력 범위, 허용 도구, 중단 조건, 증거 형식을 코드와 문서로 고정하는 층에 가깝다.
다음에 Codex AI 하네스 엔지니어링 설계 5 — 작업 분할 같은 문제를 보면 아래 순서부터 확인하려고 한다.
- 읽기·수정·실행·배포 권한 구분
- 작업마다 허용한 파일과 도구 범위
- diff·테스트·실행 화면 증거
- 반복 상한과 사람에게 돌려줄 조건
성공 문장보다 실제 diff·테스트 출력·배포 화면을 우선하고, 쓰기·배포·비밀 접근은 별도 권한 경계로 남겨야 한다.
공식 참고 자료
- OpenAI Codex 소개 — 격리된 저장소 작업·테스트·권한 경계
- Building effective agents — workflow와 agent 구분, 단순한 조합 패턴과 평가
- Codex app 소개 — 병렬 작업·sandbox·권한·검토 흐름