콘텐츠로 이동

외부 도메인 연동 (/pilot:learn)

한 줄 요약

의존성이 있는 다른 도메인의 코드를 진입점부터 N단계까지 추적 분석하여 workspace/context/{domain}.md 파일(혹은 {domain}/ 폴더)을 생성합니다. /pilot:analyze 가 기획서(docs)를 기능(features)으로 분할하는 도구라면, /pilot:learn 은 코드를 컨텍스트(context)로 변환하는 도구입니다.

전제 조건

  • 활성화된 project가 존재해야 합니다.
  • 다루려는 feature가 현재 프로젝트 도메인 외부의 코드를 참조하고 있어야 합니다 (예: coupon_service 구현을 위해 auth_service 코드를 참조해야 하는 경우).
  • 분석을 시작할 명확한 진입점(특정 파일, 폴더, 클래스명 등)을 알고 있어야 합니다.

작업 절차

1. 진입점을 지정하여 learn 실행

/pilot:learn app/services/auth/

또는 단일 파일을 지정할 수도 있습니다:

/pilot:learn app/services/external/coupon_request_service.rb

이 명령은 다음 작업을 수행합니다:

  • 진입점 코드에 대한 정적 분석을 실행하여 메소드, 라우트, 상태값, 검증 규칙 등을 추출합니다.
  • 지정된 N단계(기본값 2단계)까지 의존성 코드를 추적하여 호출되는 연계 클래스 및 모듈을 스캔합니다.
  • 코드의 규모와 구조적 복잡도에 따라 컨텍스트를 분할 저장합니다:
    • 단일 {domain}.md 파일 (규모가 작고 단순한 경우)
    • {domain}/ 디렉터리 및 다중 *.md 파일 (복잡도가 높은 경우)
  • workspace/context/MANIFEST.md 의 ## 도메인 분류 표에 새 도메인 정보를 추가 등록합니다.

추측 배제 — 비즈니스 규칙 미추출

learn 은 코드로 명시된 팩트 정보만을 file:line 인용 형태로 수집합니다. AI가 추론을 통해 주관적인 판단을 내리지 않습니다. 따라서 환불의 성격이나 상태 전이의 비즈니스적 맥락 같은 비즈니스 정책 및 규칙은 자동으로 채워지지 않으므로, 도메인 규칙 작성 가이드를 참고하여 직접 보완해야 합니다.

2. 생성된 컨텍스트 검토

ls workspace/context/
cat workspace/context/MANIFEST.md

수출된 도메인 진입점의 정보가 정확한지 훑어봅니다. 누락된 부분이 발견되면 직접 보강하거나, 추가 진입점을 지정하여 learn 명령을 재실행합니다.

3. 다음 cycle 진행 시 자동 연동

이후 planner 가 호출되면 orchestrate-load.py 가 MANIFEST.md 설정을 판별하여, 작업 대상 feature에 속하는 도메인의 컨텍스트 진입 파일을 에이전트에게 자동으로 로드합니다. 사용자가 매번 컨텍스트 파일을 주입할 필요가 없습니다.

경량 대안 — 경계 계약 모드 (--boundary)

외부 도메인 전체를 학습하기엔 비용이 크고, 실제로 필요한 것은 내 도메인이 호출하는 표면뿐인 경우가 많습니다. 이때는 boundary 모드를 사용합니다:

/pilot:learn --boundary schoice --from wms

이 명령은 wms 가 실제 호출하는 schoice 의 클래스·메서드 시그니처, 관찰된 상태값, 트랜잭션 중첩만 추출해 workspace/context/boundaries/wms--schoice.md 를 생성합니다. 전체 learn 대비 비용이 접점 크기에 비례하며, feature spec 작성에 필요한 정보 대부분을 커버합니다.

생성된 경계 문서는 별도 등록 없이 자동으로 로드됩니다 — orchestrate-load.py 가 활성 도메인 기준 정방향({domain}--*.md: 내가 호출하는 표면)과 역방향(*--{domain}.md: 다른 도메인이 나를 호출하는 표면 — 영향 분석용)을 모두 적재합니다. 미학습 외부 의존이 MANIFEST 에 기록돼 있으면 planner 호출 시 boundary 모드 처방이 힌트로 안내됩니다.

전체 learn vs boundary

경계 문서는 부분 커버입니다 — MANIFEST 의 ## 외부 도메인 reference 행은 유지되며, 이후 해당 도메인을 전체 learn 하면 행이 제거되고 도메인 산출물이 경계 문서보다 우선합니다.

다음 단계