n0ctx/dag-engineering

DAG Engineering

대규모 엔지니어링 작업을 의존 관계가 있는 하위 작업(노드)으로 분해하고, 각 노드는 하위 에이전트가 자체 워크트리와 브랜치에서 구현하며, 주 에이전트는 통합 워크트리에서 개별적으로 병합하고 검증합니다. 재작업도 이러한 격리를 유지하며, 하위 에이전트는 통합 워크트리에 들어가서 수정하거나 커밋하지 않습니다. 주 에이전트는 조사, 계획, 발송, 통합, 재작업 조정 및 최종 검증을 담당합니다. 조사 하위 에이전트는 읽기 전용으로 특정 질문에 답변합니다. 노드 하위 에이전트는 먼저 refine을 통해 세부 사항을 결정한 다음, 단일 노드를 구현하고 커밋합니다. 검토 하위 에이전트는 읽기 전용으로 검토합니다.

조사 깊이, 하위 에이전트 수 및 검증 범위는 작업의 실제 복잡성에 따라 결정됩니다. 독립적인 작업이 없으면 하위 에이전트를 사용하기 위해 분할하지 않습니다.

Codex는 하위 에이전트를 발송할 때 fork_turns="none"을 명시적으로 설정합니다.

0. 기존 계속 계획

시작하기 전에 주 작업 공간의 .dag/를 확인합니다. "plan 상태: 진행 중"인 plan이 있으면 이를 읽고, Git 실제 상태와 결합하여 현재 진행 상황에서 계속 진행하며 다시 분할하지 않습니다. plan과 Git이 일치하지 않으면 확인된 코드 상태로 plan을 수정합니다.

1. 통합 워크트리에 MERGE_HEAD가 있는 경우(git -C <통합wt> rev-parse -q --verify MERGE_HEAD): 통합이 중단되었으며 결과를 알 수 없습니다. git merge --abort를 실행한 후 해당 노드를 submitted 상태로 다시 통합합니다.
2. 노드를 하나씩 확인합니다.
   • done: 노드 커밋이 통합 브랜치에 병합되었는지 확인합니다(git -C <통합wt> merge-base --is-ancestor <커밋> HEAD). 중복 실행하지 않습니다.
   • submitted: 노드 커밋이 이미 통합 브랜치에 병합되었으면 바로 done으로 표시합니다(병합 커밋은 검증 통과 후에만 생성됨). 그렇지 않으면 6단계에 따라 통합합니다.
   • running: 현재 세션에서 에이전트가 계속 실행 중이면 기다립니다. 에이전트가 더 이상 존재하지 않으면 노드 워크트리의 커밋 및 커밋되지 않은 변경 사항을 확인하고, 같은 워크트리에서 새 에이전트가 기존 결과를 기반으로 계속 진행하도록 하고 새 워크트리를 만들지 않습니다.
   • blocked: 이유를 읽고 조건이 해제되었는지 판단합니다.
   • pending: 5단계에 따라 스케줄링합니다. 노드가 이전 형식(목표, 범위, 단계, 검수, 검증)으로 작성된 경우, 발송 전에 4단계의 템플릿으로 다시 작성합니다.
3. 모든 노드가 done이면 7단계로 계속합니다.

상태가 불분명하면 워크트리, 브랜치 또는 커밋되지 않은 변경 사항을 삭제하지 않습니다.

1. 통합 워크트리 열기

각 DAG에 대해 통합 워크트리와 브랜치를 하나 열고, 주 에이전트만 쓰며 주 작업 공간은 변경하지 않습니다.

git worktree add "../<repo>-<plan-id>" -b "dag/<plan-id>"

• <plan-id>는 이번 작업을 설명하는 짧은 kebab-case를 사용합니다. 브랜치나 디렉토리가 이미 존재하면 다른 이름을 사용합니다.
• 주 작업 공간에 커밋되지 않은 변경 사항이 있으면 사용자에게 이 변경 사항이 워크트리에 반영되지 않음을 알리고, 사용자가 먼저 커밋할지 계속할지 결정하도록 합니다.
• 검증 명령이 설치 단계(예: node_modules, 가상 환경)에 의존하는 경우, 먼저 통합 워크트리에서 설치를 완료합니다.
• 시작 커밋(git rev-parse HEAD)을 기록하고, 전체 검토의 기준으로 삼습니다.

2. 조사 및 핵심 설계

순서: 요구 사항 분석 → 대상 코드 조사 → 통합 핵심 설계.

주 에이전트는 요구 사항에 따라 기존 구현, 관련 모듈, 호출 관계 및 테스트를 찾고, 계획에 영향을 미치는 알려지지 않은 문제를 나열합니다. 모호함이 목표, 범위 또는 검수 기준을 변경할 경우 사용자에게 먼저 질문합니다. 나머지 불확실한 사항은 plan의 "가정"에 기록합니다.

여러 개의 독립적인 조사 질문이 있는 경우, 동일한 메시지에서 읽기 전용 조사 하위 에이전트를 병렬로 발송합니다. 질문이 적거나 상호 의존적인 경우 주 에이전트가 직접 조사합니다. 조사는 특정 질문(기존 구현 및 재사용, 핵심 인터페이스 및 호출 체인, 공유 상태 및 외부 리소스, 테스트 및 엔지니어링 제약 조건 등)을 기준으로 나누며, 디렉토리별로 기계적으로 나누지 않습니다. 조사 하위 에이전트는 통합 워크트리를 직접 읽으며 자체 워크트리가 필요하지 않습니다. 지침에는 다음을 명시합니다.

읽기 전용 조사 <통합wt>, 파일을 수정하지 말고 다른 에이전트를 발송하지 마십시오. 목표: <...>. 범위: <...>. 답변해야 할 질문: <질문 목록>. 질문에 답변하면 중단하고, 범위를 벗어난 탐색을 하지 않습니다. 다음만 보고합니다: 핵심 사실 및 위치(파일:심볼), 재사용 가능한 기존 구현, 엔지니어링 제약 조건, 확인되지 않은 사항. 확인된 사실과 추측을 구분합니다.

주 에이전트는 결과를 통합하고, 모순되는 결론을 처리하며, 계획에 영향을 미치는 격차만 보충 조사합니다. 노드의 goal, scope, verify 및 stop을 작성하기에 충분한 사실이 확보되면 조사를 중단합니다. steps의 세부 사항은 노드 하위 에이전트가 작업 시작 시 세부화하도록 남깁니다(5단계). 계획 수립 시 조사는 노드 경계를 결정할 수 있는 깊이까지만 합니다. 구조적 쿼리(파일 및 행 수, 호출 관계, 의존성 가장자리, 목록 항목)를 사용하여 답변하고, 함수 구현을 읽지 않습니다. 구현을 이해하는 것은 노드 하위 에이전트의 역할입니다.

교차 모듈 사실(특정 심볼이 누구에 의해 호출되는지, 특정 모듈이 무엇에 의존하는지, 일련의 파일과 그 의존성의 크기 등)은 언어 서버, ast-grep 또는 검색을 사용하여 필요에 따라 조회하며, 소스 코드 전체를 읽어 유추하지 않습니다. 한 번 조회하면 기록하여 재사용합니다. 주 에이전트나 조사 하위 에이전트가 조회한 내용은 관련 노드의 refine 결과 또는 note에 기록합니다. 노드 하위 에이전트는 보고서에 새로 발견된 교차 노드 사실을 나열하고, 주 에이전트는 이를 사용할 하류 노드의 refine에 기록합니다. 하류 노드가 작업을 시작할 때 먼저 이 기록을 확인하고, 기록이 부족하거나 관련 코드가 후속 노드에 의해 변경되어 이미 오래된 경우 다시 조회합니다.

그런 다음 plan의 "핵심 설계"를 결정하고 기록합니다.

• 목표 동작 및 비목표.
• 직접 재사용 가능한 기존 구현, 의존성 또는 플랫폼 기능.
• 기능 및 코드의 귀속.
• 교차 노드에서 일관되어야 하는 인터페이스, 데이터 구조 및 아키텍처 제약 조건.
• 공유 리소스 및 통합 조건.

교차 노드 협업에 필요한 설계만 고정하고, 노드 내부 구현은 노드 하위 에이전트에게 맡깁니다. 미래 요구 사항을 위한 추상화를 추가하지 않고, 기존 기능을 중복 구현하지 않습니다.

3. DAG 분할

• 노드 세분성: 독립적으로 검수 가능한 동작 단위를 기준으로 하며, 이를 실행 및 검증 가능하게 하는 필요한 접속을 포함합니다. 설정, 스캐폴딩, 문서는 하나의 노드만 사용할 경우 해당 노드에 통합하고, 여러 노드가 사용할 경우 상류 노드로 추출합니다. 결합도가 높거나 분할 시 검증 불가능한 중간 상태가 발생하거나 많은 중복 수정이 필요한 작업은 하나의 노드로 병합합니다. 결합도가 낮은 작업은 병렬 실행을 위해 분할합니다. 병렬성을 높이기 위해 강제로 분할하지 않습니다.
• 항목별 확인: 노드가 많은 파일이나 항목을 다루어야 하는 경우, 먼저 확인 항목과 항목별 검수 기준을 명확히 합니다. 독립적으로 확인 가능한 범위는 읽기 전용 하위 에이전트에 병렬로 처리하도록 위임하고, 격차를 종합한 후 구현합니다. 기존 확인 결론이 여전히 유효하면 재사용하고 중복 스캔하지 않습니다.
• 의존성: 하류가 상류의 코드, 결정 또는 검증된 동작을 실제로 필요로 하거나, 상류 실패 시 하류가 무효화되는 경우에만 의존성을 작성합니다. 공유 인터페이스가 핵심 설계에서 결정되어 양측이 각자 구현 및 테스트할 수 있는 경우 의존성을 작성하지 않고 병렬 실행을 허용하며, 통합 검증이 실제 연결을 확인합니다. 순서를 제어하기 위해 의존성을 조작하지 않습니다.
• 충돌: 의존성이 없지만 동시에 안전하게 실행할 수 없는 노드에만 충돌을 표시합니다. 논리적으로 영향을 미치는 수정, 데이터베이스, 포트 등 공유 실행 리소스, 마이그레이션 시퀀스 번호 등 직렬 할당이 필요한 리소스가 이에 해당합니다. 동일한 파일의 일반적인 수정 중복은 충돌로 간주하지 않고 병렬 실행을 허용하며 Git 병합으로 처리합니다. 중복이 집중되어 병합 비용이 직렬 실행보다 현저히 높은 경우에만 충돌을 표시합니다.
• 아직 실험을 통해 결정해야 하는 계획: 결론을 도출하는 조사 노드를 만들고, 하류는 이에 의존합니다.

각 노드는 4단계의 템플릿에 따라 작성합니다. 계획 수립 시 goal, scope, verify, stop, refine을 작성합니다. steps는 노드 하위 에이전트가 작업 시작 시 refine에 따라 세부화합니다(5단계). 계획 수립 시 이미 결정할 수 있는 단계는 먼저 작성할 수 있습니다.

• goal: 한두 문장으로, 완료 후 어떤 동작이 성립하는지.
• scope: 수정이 허용되는 파일 또는 디렉토리, 명시적으로 수정해서는 안 되는 부분, 준수해야 하는 핵심 설계 및 비즈니스 제약 조건.
• verify: 관찰 가능한 검수 결과와 직접 실행할 수 있는 실제 명령으로, 이 노드의 변경 사항에 영향을 받는 기존 가드(문서 크기, 코드 복잡도, 계층 및 계약 검사 등)를 포함합니다. 좁은 진입점을 우선 사용하고, 좁은 진입점이 없으면 전체 검사를 실행하지만 전체 검사는 다른 검증과 동시에 실행하지 않습니다.
• stop: 이 노드 특유의 중지 보고 조건(예: "귀속을 규칙으로 판단할 수 없음", "특정 인터페이스가 없음"). 일반 조건은 발송 지침에 이미 있으므로 중복 작성하지 않습니다.
• refine: steps를 찾기 위해 조사해야 할 사항을 실행 가능한 쿼리로 작성합니다(예: "X 접두사 아래 모든 항목과 그 의존성의 미처리 모듈 나열", "Y의 모든 호출자 나열"). 노드 하위 에이전트가 작업 시작 시 첫 번째 단계에서 완료합니다. 계획 수립 또는 조사 시 이미 찾은 결론은 refine에 직접 작성하고 "조회됨"으로 표시하여 하위 에이전트가 직접 사용하고 재조회하지 않도록 합니다. refine은 아직 답변되지 않은 항목만 쿼리로 남깁니다. 조회할 사항이 없으면 "없음"을 작성합니다.
• steps: 순서가 있는 단계로, 각 단계는 확인 가능한 한 가지 작업만 수행하며 모듈, 명령, 인터페이스 수준까지 작성합니다. 무엇을, 어디에, 외부 동작이 무엇인지를 작성합니다. 함수 수준은 경계에서만 작성합니다. 동일한 파일을 다른 노드에 할당해야 하거나 특정 함수의 귀속에 논쟁이 있는 경우, 경계 양측의 함수를 나열합니다.

소스 자료와 핵심 설계에서 이미 결정된 값, 조건, 경계는 관련 노드에 직접 작성하고 하위 에이전트가 유추하도록 남겨두지 않습니다. 파일, 심볼 및 명령은 실제 코드에서 가져와야 하며, 지어내서는 안 됩니다. 다음 작성 방식은 수정해야 합니다.

• "적절히 구현" "경계 조건 처리"와 같은 실행 불가능한 설명.
• 검수 기준이 구현 동작만 반복하는 경우(예: "X를 구현함").
• 동작 기반 검수가 파일 존재, 가져오기 가능 또는 키워드 검색으로만 입증되는 경우.
• 분류 또는 선택이 규칙 이름이나 문서 섹션(예: "D7에 따라 판단")만 참조하고 기본 동작 및 예외 조건을 작성하지 않는 경우.

발송 전에 plan을 확인하고 두 가지 질문 그룹에 답변합니다.

계획이 모두 완료된 후, 전체 검수 기준이 반드시 달성되는가. 다음 항목별로 격차를 찾습니다.

1. 범위는 실제 소스에서 열거하고 요구 사항에서만 유추하지 않습니다. 관련된 코드, 구성, 버전 관리 외부 파일 및 로컬 상태, 설치 및 배포 방식, 기타 실행 플랫폼, 외부 호출자를 포함합니다. 각 항목은 정확히 하나의 노드에 속하거나 비목표에 기록됩니다.
2. 각 검증이 성립합니다. 대상 환경에서 실행 가능해야 합니다. 실행 시 프로덕션 데이터나 외부 시스템에 쓰지 않으며, 기록이 필요한 노드는 격리 방식을 명시합니다. 통과 시 해당 검수 결론을 도출할 수 있어야 합니다. 검증에 사용되는 도구 자체가 검증되어 있어야 합니다.
3. 계획에서 도입된 임시 면제, 호환성 레이어, 전환 데이터 및 도구는 모두 제거 또는 정식화를 담당하는 노드가 있습니다.
4. 외부 시스템 쓰기, 프로덕션 환경 전환, 다른 플랫폼에서만 실행되는 경로는 전달 전에 적어도 하나의 노드가 실제 환경에서 실제로 한 번 실행됩니다.
5. 노드 간 인터페이스 및 아키텍처가 일관됩니다. 의존성, 충돌에 오류나 누락이 없습니다. 노드 간 통합을 담당하는 노드가 있습니다. 각 노드의 refine이 steps를 찾을 수 있고 verify가 모두 실행 가능합니다.

격차는 노드로 보충합니다. 보충할 수 없거나 보충 비용이 사용자의 선택을 필요로 하는 경우 plan의 "완성도 격차"에 기록하고 사용자에게 결정을 맡깁니다.

설계가 시간을 낭비하는가.

6. 각 노드의 산출물에 하류 사용자가 있으며, 검증도 포함됩니다. 사용자가 없는 노드는 삭제합니다.
7. 사용자의 결정이나 참석이 필요하거나 기존 동작을 변경하는 노드는 다른 노드가 기다리도록 하지 않습니다. 하류가 이를 기다려야 하는 경우, 동작을 변경하지 않는 부분(먼저 수행)과 변경하는 부분(나중에 수행)으로 분할합니다.
8. 두 개 이상의 노드가 사용하는 동일한 기능이나 도구는 상류 노드로 추출하여 각 노드가 각자 구현하지 않도록 합니다. 각 노드의 verify가 무엇에 의해 입증되는지 확인합니다. 두 개 이상의 노드가 동일한 검증 수단(이전-이후 비교, 재생, 결과 비교 등)을 사용하는 경우, 이를 상류 도구 노드로 추출합니다. 이 노드의 verify는 알려진 차이가 있는 샘플을 사용하여 도구가 차이를 보고할 수 있음을 입증하는 것을 포함합니다. 두 개 이상의 노드가 동일한 대규모 자료(목록, 매핑 테이블, 결정 문서)를 반복적으로 조회해야 하고 프로젝트에 필요한 쿼리 진입점이 없는 경우, 상류 노드를 만들어 쿼리 진입점을 추가합니다.
9. 각 노드가 읽고 수정해야 하는 양(scope 내 파일과 의존하고 아직 처리되지 않은 코드를 더한 양)을 추정합니다. 양이 하위 에이전트가 안정적으로 완료하기 어렵거나, 서로 관련이 없고 각자 독립적으로 검수할 수 있는 모듈에 걸쳐 있는 경우 분할합니다. 응집력이 강하고 분할 시 검증 불가능한 중간 상태가 발생하는 경우 양이 많아도 분할하지 않습니다. 행 수는 판단 기준일 뿐 고정 임계값은 설정하지 않습니다. 추정할 수 없는 경우, 계산할 내용을 refine에 작성하고 노드 하위 에이전트가 작업 시작 시 첫 번째 단계에서 추정하도록 합니다. 분할 방법은 워크트리를 만들기 전에 결정해야 하며, 5단계에 따라 먼저 조사 하위 에이전트를 발송하여 추정합니다.
10. 기존 기능을 중복 구현하지 않고, 불필요한 분할이나 과도한 설계가 없으며, 안전하게 병렬 실행할 수 있는 노드가 직렬로 실행되지 않습니다.

노드가 5개 이하이면 주 에이전트가 검사합니다. 5개를 초과하면 먼저 초안을 4단계에 따라 .dag/<plan-id>.md에 작성한 다음, 읽기 전용 하위 에이전트를 발송하여 검토하도록 합니다. 이 하위 에이전트에게는 plan, 요구 사항 및 코드 위치만 제공하고 주 에이전트의 추론 과정은 제공하지 않습니다.

읽기 전용 검토 <plan 경로>, 파일을 수정하지 말고 다른 에이전트를 발송하지 마십시오. 요구 사항: <원본 요구 사항 또는 위치>. 코드: <통합wt>. 다음 항목별로 하나씩 검사합니다: <위 1~10항목 원문>. 다음만 보고합니다: 목표 완성을 위한 격차, 시간 낭비 설계, 사용자 결정이 필요한 사항. 각 항목에 위치, 증거(파일:심볼, 명령 출력 또는 plan 원문) 및 최소 수정 제안을 작성하고, 확인된 문제와 추측을 구분합니다.

주 에이전트는 구체적인 증거가 있는 문제만 수정합니다.

4. plan 저장

주 작업 공간의 .dag/<plan-id>.md에 작성하며, 워크트리에 넣지 않아 커밋을 방지합니다. .dag/가 Git에 무시되지 않으면 .git/info/exclude에 추가합니다.

# <plan-id>

- 목표:
- 전체 검수 기준:
- 비목표:
- 가정:
- 완성도 격차: <계획 완료 후에도 보장할 수 없는 부분과 사용자의 결정. 없으면 "없음">
- 핵심 설계:
- plan 상태: 진행 중
- 통합 워크트리: <경로>   브랜치: dag/<plan-id>   시작점: <sha>
- 인터페이스 기록: `.dag/<plan-id>-interfaces.md`

## 노드

### N1 <제목>
#### goal
#### scope
#### steps
<노드 하위 에이전트가 작업 시작 시 세부화>
#### verify
#### stop
#### refine
#### state
- 의존성: 없음
- 충돌: 없음
- 상태: pending
- worktree:   브랜치:   커밋:

## 실행 기록
- N1: <병합 커밋 sha> <한 줄 결과>.<재작업, 예외 또는 남은 문제. 없으면 작성하지 않음>

인터페이스 기록 파일은 plan과 함께 보관하며, 각 노드가 병합될 때 섹션을 추가합니다. 노드 하위 에이전트는 읽기 전용으로 읽을 수 있습니다.

## N1(<병합 커밋 sha>)
- <인터페이스, 명명 및 위치>: <형태와 사용법>

실행 기록은 결과와 남은 문제만 작성합니다. 외부 인터페이스는 인터페이스 기록 파일에 작성하고, 교차 노드 사실은 이를 사용할 하류 노드의 refine에 작성하며, 대조 차이 등의 세부 사항은 노드의 커밋 메시지와 보고서 파일에 남깁니다.

goal에서 refine까지는 노드 하위 에이전트에 전달됩니다. state는 주 에이전트만 사용합니다.

상태 값:

• pending: 발송되지 않음.
• running: 하위 에이전트가 구현 또는 재작업 중.
• submitted: 하위 에이전트가 커밋했으며 통합을 기다리는 중.
• done: 통합 브랜치에 병합되고 주 에이전트의 검수를 통과함.
• blocked: 계속할 수 없으며 이유를 실행 기록에 기록.

plan은 주 에이전트만 수정합니다. 상태가 변경될 때마다 즉시 업데이트하며, 이는 세션 간 작업을 계속하는 근거가 됩니다.

저장 후 사용자에게 노드, 의존성, 병렬 가능한 노드, 완성도 격차 및 모든 사용자 결정이 필요한 사항을 간략히 표시합니다(한 번에 모두 나열, 나누어 묻지 않음). 사용자가 계획만 요청한 경우 여기서 멈춥니다. 그렇지 않으면 계속 실행합니다.

5. 동적 발송

의존성이 모두 done이고 running/submitted 노드와 충돌이 없는 pending 노드가 준비된 노드입니다. 모든 준비된 노드를 찾아 동일한 메시지에서 병렬로 발송하며, 고정된 동시 실행 상한은 설정하지 않고 실제 동시 실행은 에이전트 도구와 환경이 허용하는 대로 합니다. 이후 노드가 done될 때마다 즉시 준비된 노드를 다시 찾아 발송하고, 다른 독립적인 노드가 끝날 때까지 기다리지 않습니다.

각 노드를 발송하기 전에 주 에이전트는 사전 확인만 수행합니다. 이 노드가 사용하는 상류 결정, 인터페이스, 명명 및 규칙을 나열하고 모두 통합 브랜치 HEAD에 병합되었는지 확인합니다. 그중 어떤 항목이 running 또는 pending 노드에 의해 변경될 예정이면 이 노드에 의존성을 추가하고 발송을 보류합니다.

refine의 쿼리는 노드 하위 에이전트가 작업 시작 시 첫 번째 단계에서 완료하며, 주 에이전트는 직접 실행하지 않습니다. 다음 두 가지 예외는 먼저 2단계에 따라 읽기 전용 조사 하위 에이전트를 발송하고 결론만 받습니다.

• 노드가 병렬로 실행 가능한 여러 노드로 분할될 수 있고, 분할 방법을 워크트리 생성 전에 결정해야 하는 경우: 조사 하위 에이전트가 refine에 따라 규모와 결합도를 추정하고, 주 에이전트는 3단계 9항목에 따라 분할한 후 각각 발송합니다.
• 여러 준비된 노드가 동일한 문제를 조회해야 하는 경우: 하나의 조사 하위 에이전트를 발송하여 함께 답변하고, 노드당 하나씩 발송하지 않습니다.

그런 다음 통합 브랜치의 현재 HEAD(가장 최근에 검증된 통합 커밋)에서 노드 워크트리를 생성하고, 경로와 브랜치를 plan에 기록하고 running으로 표시합니다.

git -C <통합wt> worktree add "../<repo>-<plan-id>-<node-id>" -b "dag-node/<plan-id>/<node-id>" HEAD

검증 의존성 설치 단계가 필요한 경우, 지침에서 노드 하위 에이전트가 자체 워크트리에서 먼저 설치를 완료하도록 요청합니다.

노드 하위 에이전트에 대한 지침은 다음 순서로 구성하며, 이 내용만 포함합니다.

1. 워크트리 경로 및 브랜치.
2. 해당 노드 plan의 goal, scope, steps(있는 경우), verify, stop, refine의 원문.
3. note(지침에만 작성하고 plan에는 기록하지 않음):
   • 인터페이스 기록 파일의 절대 경로. 경로만 제공하고 지침에서 상류 인터페이스를 반복하지 않습니다.
   • 이 노드 특유의 추가 사항: 주 에이전트가 정한 경계와 선택, 사용자 결정의 원문, 이 노드에만 관련된 상류 사실, 알려진 함정, 자료 조회 명령. 일반적으로 약 20줄을 초과하지 않습니다. 자료가 약 200줄을 초과하거나 일부만 사용되는 경우, 발췌 또는 조회 명령을 제공하고 파일 경로만 제공하지 않습니다. 프로젝트 설명 파일은 하위 에이전트가 자동으로 로드하므로 이미 작성된 규칙은 반복하지 않습니다. verify에서 출력이 긴 명령의 경우, 어느 부분(예: 끝의 요약 행)을 볼지 명시합니다.
   • 보고서 파일 경로: .dag/<plan-id>-reports/<node-id>.md(주 작업 공간의 절대 경로).
4. 다음 요구 사항을 지침 마지막에 배치합니다.

주어진 워크트리 내에서만 작업하고, 통합 브랜치, 다른 노드의 브랜치 또는 워크트리를 조작하지 않으며, 다른 에이전트를 발송하지 마십시오. 지침에 제공된 보고서 파일 외에는 .dag/ 아래 파일을 수정하지 마십시오. 인터페이스 기록 파일 외에는 .dag/ 아래 파일을 읽지 마십시오. 프로젝트 설명 파일에 메인 세션을 위한 시작 및 종료 단계(계획 읽기, 상태 확인 실행, plan 복원 등)는 귀하에게 적용되지 않습니다. 자료를 조회할 때는 먼저 note에 제공된 명령과 발췌문을 사용하고, note가 다루지 않은 경우 직접 조회하십시오. plan, 결정 문서 또는 대규모 목록을 전체적으로 읽지 마십시오.

두 단계로 작업합니다. 첫 번째 단계: refine에 따라 사실을 조사하고(refine에 "조회됨"으로 표시된 결론은 직접 사용하고, 아직 답변되지 않은 항목만 조회), goal, 인터페이스 및 scope를 변경하지 않고 steps를 결정하고(모듈, 명령, 인터페이스 수준까지 작성, 동일한 파일을 다른 노드와 분리해야 하는 경우 경계 양측의 함수 나열), 읽고 수정해야 하는 양을 추정합니다. 다음 상황 중 하나가 발생하면 중단하고, 약 30줄을 초과하지 않는 요약(steps 초안, 추정량, 제안된 분할 방법, 주 에이전트 또는 사용자 결정이 필요한 사항)을 반환하여 응답을 기다립니다. 경계 또는 귀속을 판단할 수 없음, 교차 노드 인터페이스를 변경하거나 scope 외부 파일을 수정해야 함, 실제 코드가 노드 설명과 충돌함, 양이 하위 에이전트가 안정적으로 완료하기 어렵거나 각자 독립적으로 검수할 수 있는 모듈에 걸쳐 있음, stop에 나열된 상황이 발생함. 이러한 상황이 없으면 멈추지 않고 바로 두 번째 단계로 진행하며, 요약은 최종 보고서에 포함됩니다.

두 번째 단계: steps에 따라 구현하고, goal, 인터페이스 및 scope를 변경하지 않고 로컬 구현 방식을 스스로 결정합니다. verify의 명령을 실행하고 통과한 후 이 노드의 모든 변경 사항을 커밋합니다. 커밋 메시지는 <plan-id>/<노드>: <요약> 형식이며, git status가 깨끗한지 확인합니다. 검증을 통과하지 못하면 커밋하지 않습니다. 두 번째 단계에서 첫 번째 단계에 나열된 중단 상황이 발생하거나 실제 양이 첫 번째 단계 추정량의 약 2배를 초과하면 중단하고 보고하며, 스스로 확장하지 마십시오. 완료된 부분이 verify에서 적용 가능한 명령을 통과하면 먼저 커밋하고, 그렇지 않으면 워크트리에 유지하고 커밋하지 않으며, 보고서에 완료된 작업과 남은 작업을 나열합니다.

종료 또는 중단 시, 전체 보고서(변경 요약, 검증 명령 및 전체 결과, 대조 차이, 편차 설명)를 보고서 파일에 작성하고, 주 에이전트에게 약 40줄을 초과하지 않는 내용만 반환합니다: 상태(DONE: 완료 및 검증 통과, DONE_WITH_CONCERNS: 완료되었지만 우려 사항 있음, BLOCKED: 완료 불가능 또는 중단), 커밋 sha, 검증 결과 한 줄, 외부 인터페이스의 추가 또는 변경, 새로 발견된 교차 노드 사실(예: 특정 심볼이 어떤 모듈에 의해 계속 사용되는지, 특정 인터페이스의 실제 형태), 우려 사항 또는 차단 이유, 결정이 필요한 사항.

하위 에이전트가 첫 번째 단계에서 중단하고 요약을 반환하면, 주 에이전트는 경계와 결정이 필요한 사항(사용자 결정이 필요한 것은 먼저 질문)을 확인하고, 확인된 steps를 plan에 다시 작성한 다음, 에이전트 도구의 연속 기능(Claude Code의 SendMessage, Codex는 동일한 에이전트에 후속 입력 전송)을 사용하여 동일한 하위 에이전트가 두 번째 단계를 계속하도록 하고, 새 에이전트를 발송하지 않아 이미 읽은 코드를 다시 읽지 않도록 합니다. 분할을 제안하는 경우, 6단계 "plan 자체 오류" 규칙에 따라 분할합니다. 원래 에이전트는 그중 일부를 계속하고, 나머지 부분은 새 노드로 5단계부터 발송합니다. 원래 에이전트를 계속 사용할 수 없으면 동일한 워크트리에서 새 에이전트를 발송하고 요약을 첨부합니다.

하위 에이전트가 커밋을 반환하면 커밋 sha를 plan에 기록하고 submitted로 표시한 후 6단계로 진행합니다.

대기 규칙(조사, 검토 하위 에이전트에도 동일 적용):

• 하위 에이전트 범위와 충돌하지 않는 구체적이고 독립적인 작업(예: 이미 제출된 노드 통합)이 있으면 먼저 완료하고, 없으면 기본 대기 상태로 들어갑니다.
• Claude Code는 백그라운드 에이전트의 완료 알림 또는 기본 대기를 사용합니다. Codex는 직접 에이전트 도구를 호출하고 functions.exec 또는 functions.wait에 넣지 않습니다. wait_agent는 timeout_ms=600000으로 설정하고, 도구 매개변수가 이 값을 지원하지 않으면 허용되는 최대 대기 시간을 사용합니다. 도구가 일괄적으로만 결과를 반환할 수 있으면 해당 기능에 따라 처리하고, 존재하지 않는 알림을 시뮬레이션하지 않습니다.
• 루프를 사용한 짧은 sleep, 에이전트 목록 조회 또는 Git 상태 반복 확인으로 대기를 대체하지 않으며, 진행 상황 업데이트를 보내기 위해 대기 시간을 단축하지 않습니다.
• 결과 또는 사용자 메시지를 받은 후 즉시 처리합니다. 대기 시간 초과만으로는 실패를 의미하지 않습니다. 계속 대기하고, 아직 실행 중인 노드를 다시 발송하지 않습니다.

6. 노드별 통합 검수

주 에이전트는 통합 워크트리에서 한 번에 하나의 submitted 노드를 통합하며, 다른 하위 에이전트는 계속 작업합니다. 하위 에이전트의 보고를 직접 신뢰하지 않습니다.

1. git -C <통합wt> diff --stat HEAD...<노드 브랜치>: 변경된 파일이 모두 노드 scope 내에 있는지 확인합니다. 노드 워크트리의 git status에 남은 커밋되지 않은 변경 사항이 없는지 확인합니다. 그런 다음 다른 노드와 공유하는 파일(공용 모듈, 구성, 가드 기준선, 목록, 계약 테스트)의 전체 diff를 확인하여 goal 및 핵심 설계에 부합하는지 확인합니다. 노드 자체의 새 코드는 3단계의 검증과 실제 측정 동작으로 판단하고, 한 줄씩 읽지 않습니다. 세부 사항이 필요하면 보고서 파일의 관련 단락을 읽습니다.
2. 병합하지만 아직 커밋하지 않습니다.

   git -C <통합wt> merge --no-ff --no-commit "dag-node/<plan-id>/<node-id>"
   

3. 통합 워크트리에서 해당 노드 verify의 명령과 병합의 영향을 받는 통합 검사를 실행합니다. verify의 검수 결과를 항목별로 확인하고, 적어도 하나의 동작을 실제로 검증합니다. 영향을 받은 가드의 새로운 실패는 이 노드에서 수정하고 최종 검증까지 남기지 않습니다. 기존 실패는 별도로 기록하고, 임계값이나 기준선을 완화하지 않습니다. 매번 전체 테스트 스위트를 실행할 필요는 없습니다.
4. 모두 통과: git -C <통합wt> commit --no-edit, 노드를 done으로 표시하고, 한 줄의 실행 기록을 작성하며, 외부 인터페이스를 인터페이스 기록 파일에 추가하고, 교차 노드 사실을 이를 사용할 하류 노드의 refine에 기록한 후, 5단계로 돌아가 새로 잠금 해제된 노드를 발송합니다.

목록 적용 검수는 항목별로 확인된 결론, 확인할 항목 및 격차를 기록해야 합니다. 선언된 모든 범위가 확인되고 검수 기준을 충족하는 경우에만 done으로 표시할 수 있습니다. 파일 존재, 본문이 비어 있지 않음 또는 샘플 통과는 항목별 적용을 대체할 수 없습니다.

병합 중 충돌이 발생하면, 양측 의도가 명확한 일반적인 중복은 주 에이전트가 직접 해결한 후 3단계를 실행합니다.

나머지 충돌 또는 검사 불통과 시, 완료되지 않은 병합을 취소하고(git -C <통합wt> merge --abort), 통합 브랜치는 이전의 승인된 커밋 상태를 유지하며, 노드 커밋은 노드 브랜치에 유지됩니다. 문제 귀속에 따라 처리합니다.

• 노드 구현 결함: 노드를 running으로 다시 표시하고, 구체적인 문제를 원래 노드 하위 에이전트에게 원래 워크트리에서 수정 후 다시 제출하도록 전달합니다. 원래 에이전트를 계속 사용할 수 없으면 동일한 워크트리에서 새 에이전트를 발송하여 계속합니다. 주 에이전트는 기본적으로 노드 구현을 직접 다시 작성하지 않습니다.
• 노드가 최신 통합 결과를 참조해야 하는 충돌: 노드 하위 에이전트가 자체 워크트리에서 dag/<plan-id>를 병합한 후 충돌을 해결하고, 다시 검증하고 커밋하도록 합니다.
• 교차 노드 인터페이스 또는 논리 충돌: 주 에이전트가 올바른 설계를 결정하고, plan의 핵심 설계 및 관련 노드를 업데이트한 다음, 관련 노드 하위 에이전트에게 조정을 전달합니다.
• plan 자체 오류(scope, steps, 의존성 또는 verify가 실제 코드와 일치하지 않음): 새로 발견된 코드 사실을 기반으로 영향을 받는 노드, 의존성 및 검수만 수정하고, 유효한 완료 결과는 유지하며, 전체 DAG를 재설계하지 않습니다. 수정이 전체 검수 기준 또는 비목표에 영향을 미치는 경우 먼저 사용자에게 질문합니다.
• 하위 에이전트가 DONE_WITH_CONCERNS를 보고: 우려 사항이 검수 기준에 영향을 미치면 불통과로 처리합니다. 그렇지 않으면 정상적으로 통합하고 우려 사항을 실행 기록에 기록합니다.
• 하위 에이전트가 실제 양이 추정치를 초과하여 중단: 이미 커밋된 부분이 독립적으로 검수 가능하면 이 노드의 goal, scope, verify를 완료된 부분으로 변경하고 이 단계에 따라 통합합니다. 남은 작업은 "plan 자체 오류"에 따라 새 노드로 분할하고 5단계부터 발송합니다. 이미 커밋된 부분이 독립적으로 검수 불가능하면 통합하지 않고 노드를 running 상태로 유지하며, 남은 작업을 해당 노드의 steps에 작성하고, 동일한 워크트리에서 새 에이전트를 발송하여 기존 결과를 기반으로 계속합니다.
• 하위 에이전트가 BLOCKED를 보고하거나 노드를 계속할 수 없음: blocked로 표시하고 구체적인 이유를 기록하며, 이에 의존하는 노드는 발송하지 않고 다른 노드는 계속합니다. 준비되거나 실행 중인 노드가 없지만 blocked 노드가 있는 경우 중단하고 사용자에게 차단 이유를 보고하며, 사용자 결정을 기다린 후 계속합니다. 7단계로 진행하지 않습니다.

노드가 done되면 워크트리와 브랜치를 정리합니다. 워크트리에 커밋되지 않은 변경 사항이 있으면 중단하고 확인하며, --force 또는 -D를 사용하지 않습니다.

git -C <노드wt> status --porcelain
git -C <통합wt> worktree remove "<노드wt>"
git -C <통합wt> branch -d "dag-node/<plan-id>/<node-id>"

blocked, 재작업 중 또는 상태가 불분명한 노드는 워크트리와 브랜치를 유지합니다.

7. 전체 검토

모든 노드가 done되면, 읽기 전용 하위 에이전트를 발송하여 통합 브랜치의 전체 변경 사항을 검토합니다.

읽기 전용 검토 <통합wt>에서 <시작sha>..HEAD의 모든 변경 사항, 파일을 수정하지 말고 다른 에이전트를 발송하지 마십시오. 다음 목표, 전체 검수 기준 및 비목표를 기준으로 검사합니다: 요구 사항 적용, 교차 노드 인터페이스 및 동작의 일관성, 중복 구현, 핵심 설계를 벗어난 아키텍처, 정확성 결함, 남아 있는 디버깅 또는 임시 코드, 중요한 테스트 누락 또는 주장된 동작을 실제로 적용하지 않음. 각 문제에 대해 위치, 증거 및 관련 노드를 제공하고, 확인된 문제와 추측을 구분합니다. 또한 사용자 결정이 필요한 사항을 별도로 나열합니다.

지침에 plan의 목표, 전체 검수 기준, 비목표 및 핵심 설계를 첨부합니다.

주 에이전트는 각 문제를 확인한 후 귀속에 따라 수정을 조정합니다. 구현이 필요한 문제는 plan에 수정 노드(예: F1)로 작성하고 5-6단계에 따라 발송 및 통합합니다. 국부적이고 명백한 작은 문제(예: 남아 있는 디버깅 문장)는 주 에이전트가 통합 워크트리에서 직접 수정하고 커밋할 수 있습니다. 사용자 결정이 필요한 사항은 스스로 결정하지 않고 보고서에 기록합니다.

8. 최종 검수 및 보고

주 에이전트는 통합 워크트리에서 다음 검사를 완료합니다.

1. <시작sha>..HEAD의 전체 diff를 확인하여 plan 목표를 벗어난 변경 사항이 없는지 확인합니다.
2. 모든 노드의 검증 명령과 프로젝트에서 변경 모듈을 포함하는 테스트, 빌드 및 린트 명령을 실행합니다.
3. 전체 검수 기준을 항목별로 확인합니다.

검사 실패 시: 문제가 plan 목표 내에 있으면 7단계의 귀속 규칙에 따라 수정한 후 다시 검사합니다. 문제가 plan 목표 내에 없으면(예: 시작 시 이미 실패한 테스트) 수정하지 않고 보고서에 기록합니다. 모든 작업이 완료되면 "plan 상태"를 "완료됨"으로 변경합니다.

최종 보고서에는 다음이 포함됩니다: 완료된 노드 및 해당 병합 커밋, 검토 발견 사항 및 처리, 검증 결과, 완료되지 않았거나 위험이 있는 사항, 사용자 결정이 필요한 사항, 통합 워크트리 경로 및 브랜치, 유지되는 노드 워크트리. 대상 브랜치에 병합하고 통합 워크트리를 삭제하는 것은 사용자가 요청할 때만 수행합니다.