도메인 암묵지 기록

한 줄 요약

/pilot:learn 은 코드에 명시된 객관적 사실만 추출합니다. 의도나 비즈니스 맥락처럼 암묵지 형태로만 존재하는 도메인 지식은 사용자가 에이전트와 협업하여 명문화한 뒤 context/ 디렉터리에 기록해야 합니다. 본 가이드는 에이전트를 활용해 암묵지를 끌어내는 프롬프트 작성법과 기록 요령을 설명합니다.

왜 필요한가 — learn 명령어가 수집하지 못하는 지식

learn 의 결과물은 코드에 작성된 형태 그대로를 추출한 정보입니다 (메소드 시그니처, 라우트, 상태값, file:line 인용 등). 하지만 핵심 도메인 지식의 상당수는 다음과 같이 코드 외부의 암묵지 형태로 숨겨져 있습니다:

• 코드상에 존재하나 의도를 파악하기 힘든 경우: 매직 넘버, 특정 호출 순서에 대한 의존성, 복잡한 분기 처리 등. 코드는 동작의 대상(What)은 보여주지만, 그렇게 설계한 이유(Why)는 명시하지 않습니다.
• 코드 외부에만 존재하는 경우: 비즈니스 정책의 수립 배경, 과거의 장애 대응 이력, 도메인 용어의 고유한 의미, 개발자의 머릿속에만 담긴 암묵적 제약사항 등.

이러한 암묵지 정보가 컨텍스트에서 누락되면 AI와 새로 합류한 개발자는 잘못된 판단을 내릴 위험이 큽니다. learn 은 "추측 배제" 원칙에 따라 이러한 정보를 스스로 지어내지 않으므로, 사람이 직접 이를 수집하고 기록해야 합니다.

전제 조건

• /pilot:learn 을 통해 도메인의 구조적 정보가 이미 추출되어 있어야 합니다 (외부 도메인 연동 참고).

암묵지 추출하기 — 에이전트와 협업

핵심 원칙: 에이전트에게 정보를 스스로 상상하여 작성하게 하지 말고, 질문을 던지도록 유도하십시오. 암묵지의 정답은 코드가 아닌 도메인 지식을 가진 사람에게 있습니다. 아래와 같은 프롬프트 패턴을 활용해 보십시오:

• 공백 영역 찾기: "이 도메인 문서에서 코드 분석만으로는 그 이유(Why)를 명확히 파악할 수 없는 지점들을 찾아내어, 도메인 전문가에게 질의할 질문 리스트를 작성해줘. 임의로 추측하여 답을 채워 넣지 마."
• 인터뷰 생성: learn 수행 결과물을 주고 "이 코드의 비즈니스적 의도를 파악하기 위해 핵심 설계자에게 던져야 할 핵심 질문 목록만 뽑아줘."
• 초안 구조화: 내가 알고 있는 거친 형태의 단편적인 내용을 던진 뒤 "내가 구두로 설명한 이 정보를 도메인 규칙 문서 템플릿에 맞추어 깔끔하게 다듬어줘. 설명하지 않은 미확인 정보는 지어내지 말고 _(추가 예정)_ 로 명시해둬."
• 용어집 구성: "이 코드베이스에 등장하는 용어 중, 보편적인 사전적 의미와는 다르게 우리 도메인에서 특수하게 쓰이는 단어들을 추려줘."

피해야 할 유의사항:

• 에이전트가 "코드 구조상 아마 이렇기 때문일 것"이라며 자의적인 추론 결과를 올바른 정보인 양 기록하도록 방치하는 행위 (추측은 팩트가 아닙니다).
• 처음부터 단번에 완벽한 지식 문서를 작성하려 애쓰는 행위 (암묵지는 개발 주기가 흘러가며 점진적으로 포착되고 완성됩니다).

무엇을 기록할 것인가

지식 유형	예시
비즈니스 규칙 및 정책	"환불을 결제 후 7일로 제한"하는 구체적인 비즈니스 의사결정 배경과 예외 정책
도메인 용어집	해당 도메인에서만 통용되는 고유 의미 정의 (예: 도메인의 정산 ≠ 일반 회계의 정산)
암묵적 제약 및 호출 순서	"A 모듈을 호출하기 전 반드시 B 모듈을 초기화해야 한다" 와 같이 코드 상으로 강제되지 않은 연계 조건
역사적 히스토리 및 예외 처리	"이 분기문은 2023년 데이터 마이그레이션 호환성을 보존하기 위한 코드로, 신규 연동 시에는 적용 대상에서 제외함"
엣지 케이스 및 위험 요소	빠지기 쉬운 함정 및 과거 장애 발생 원인
외부 연동 사양	공식 문서에는 명시되지 않은 외부 연동 API의 실제 런타임 동작 방식

어떻게 기록할 것인가

• 출처 표기: 각 규칙에는 file:line 코드 인용을 달거나, "PM 결정 사안 (2024-03)", "구두 확인: {담당자 이름}" 과 같이 근거 출처를 남겨 신뢰성을 담보합니다.
• 모르는 항목은 비워둠: 확실치 않은 내용은 억지로 채우지 말고 _(추가 예정)_ 로 명시한 뒤 확인되면 갱신합니다.
• 선언적 기술: 정책과 제약은 줄글과 표 형태로 깔끔하게 설명하며, 코드 블록을 그대로 복사해 넣지 않습니다.
• 적절한 문서 매칭: 비즈니스 정책은 도메인 규칙 문서에, 용어 정의는 도메인 문서 최상단에 작성하고, 구조적 사실은 learn 산출물 영역에 둡니다.
• MANIFEST 연동: 새로 만든 지식 문서가 에이전트에 정상 로드되도록 반드시 MANIFEST.md 파일에 해당 경로를 추가 등록해야 합니다.
• 점진적 갱신: 개발 및 디버깅 과정에서 새로운 암묵지를 발견하는 즉시 문서를 보완합니다. 에이전트 역시 작업 중 설계 불일치나 새로운 맥락을 발견하면 Drift Protocol에 따라 직접 수정하는 대신 수정 제안을 리포팅합니다.

다음 단계

• How-to: 도메인 규칙 작성 — 추출해 낸 비즈니스 정책을 문서화하여 정리하는 방법.
• Explanation: Drift Protocol — 개발 주기에 맞춰 지식을 동기화하고 변경 제안을 처리하는 절차.
• How-to: 워크스페이스 설정 — 도메인 지식이 아닌 런타임 실행 환경에 필요한 설정 방법.