SOP: 보이지 않는 지식을 저장소에 인코딩하기

중요한 컨텍스트(context)가 여전히 Google Docs, 채팅 스레드, 티켓, 혹은 사람들의 머릿속에만 있을 때 이 표준 작업 절차(SOP)를 사용하십시오.

에이전트(agent)에게 보이지 않는 지식이란 저장소 어디에도 기록되지 않아 새로운 세션에서는 발견할 수 없는 암묵지를 말합니다. 이를 저장소 로컬 파일로 옮기는 것이 시스템 오브 레코드(system-of-record)로서의 저장소 원칙의 핵심입니다.

목표

에이전트에게 보이지 않는 지식을 코드베이스에서 발견 가능하게 만들어, 새 세션이 이전 대화에 의존하지 않고 바로 작업할 수 있게 합니다.

트리거 신호

• 에이전트가 시스템 동작 방식을 계속 질문한다.
• "우리가 Slack에서 결정했어요" 또는 "지난 주에 X가 말한 대로 해주세요"라는 말이 나온다.
• 리뷰에서 저장소 내에 기록되지 않은 제품 또는 보안 규칙을 참조한다.
• 새 세션이 이미 해결됐어야 할 탐색 작업을 반복한다.

실행 절차

1. 보이지 않는 지식 출처를 목록으로 작성한다: 문서, 채팅, 암묵적인 팀 규칙, 구두 결정.
2. 각 출처에 대해 묻는다: 이것이 아키텍처, 제품 동작, 보안 정책, 신뢰성(reliability) 기대치, 계획 컨텍스트, 또는 참고 자료인가?
3. 해당하는 저장소 산출물(artifact)에 인코딩한다:
   • 아키텍처 -> ARCHITECTURE.md
   • 제품 동작 -> docs/product-specs/
   • 설계 근거 -> docs/design-docs/
   • 실행 상태 -> docs/exec-plans/
   • 반복적인 외부 참고 자료 -> docs/references/
   • 품질 또는 신뢰성 기대치 -> docs/QUALITY_SCORE.md 또는 docs/RELIABILITY.md
4. 모호한 서술을 운영 관점에서 유용한 표현으로 교체한다.
5. 오래된 사본을 제거하거나 폐기(deprecate)하여 저장소가 하나의 발견 가능한 진실을 유지하도록 한다.

올바른 인코딩 규칙

• 문학적 완결성이 아닌 발견 가능성을 위해 작성한다.
• 명확한 파일명을 가진 짧은 문서를 선호한다.
• 관련 산출물들을 서로 연결한다.
• 회의록이 아닌 지속적인 규칙을 저장한다.
• 결정이 내려진 동일한 세션에서 저장소를 업데이트한다.

완료 정의

• 새로운 에이전트가 사람에게 묻지 않고 관련 규칙을 발견할 수 있다.
• 동일한 사실이 여러 모순된 파일에 흩어져 있지 않다.
• 새 산출물은 그것이 관장하는 코드 또는 워크플로우 가까이에 위치한다.