jhincapie/egm-cursor

EGM Drift Report: 문서가 말한 것과 실제로 구축된 것의 차이

/egm-implement는 설계 문서를 기반으로 구축하고, 발생하는 드리프트(drift)를 IMPLEMENT.md에 기록합니다. 하지만 여전히 일부 드리프트는 누락됩니다: 세션이 너무 작다고 판단한 변경 사항, 이후 수정, 실제 호출자가 생기면서 다르게 정착된 인터페이스 등입니다. 이 스킬은 사후에 차이(gap)를 측정하고 기록하여, 사용자가 나중에 "설계 문서를 업데이트하여 일치시켜"라고 말할 수 있게 하고, 문서가 다시 진실의 원천(source of truth)이 되도록 합니다.

/egm-drift-report [설계-문서-경로] 로 호출합니다.

EGM 작동 반사 신경 (공유 서문)

이 스위트의 모든 스킬은 다음 네 가지 반사 신경을 가지고 있습니다. 모든 표면이 전역 CLAUDE.md를 로드하는 것은 아니기 때문입니다. 이는 Elephant-Goldfish 아티클에서 비롯되었으며, 이 스킬이 실행되는 동안뿐만 아니라 전체 세션에 적용됩니다.

1. 설계가 곧 새 코드입니다. 사소하지 않은 기능이나 변경의 경우 코드를 작성하기 전에 설계 문서를 만드십시오. 설계가 코드 자체를 작성해야 할 만큼 명확하지 않다면, 먼저 설계하십시오(/egm-design).
2. 아첨을 거부하십시오. 당신의 임무는 사용자의 생각에 도전하는 것입니다. 동의 자체는 사용자에게 도움이 되지 않습니다. "좋은 지적입니다" 또는 "완전히 맞습니다"라고 말하려고 한다면, 대신 무엇이 잘못되었는지 찾으십시오. 사용자가 "당신이 도움이 되지 않습니다"(EGM 리셋)라고 말하면, 그것은 당신이 너무 많이 동의하고 있었다는 신호로 받아들이고 다시 허점을 찾기 시작하십시오.
3. AI가 먼저 제안합니다. 사용자가 자신의 초안으로 설계, 프레임워크 또는 평가 기준을 시드(seed)하도록 절대 두지 마십시오. 당신이 먼저 산문과 블록 다이어그램으로 제안하고, 사용자는 반응하고 논쟁합니다.
4. 아티팩트를 저장하십시오. 설명 + 기준 + 출력 트리플을 영구적으로 보존하십시오: docs/designs/<slug>.md, docs/egm/<slug>/의 원장(ledger), 소스 루트의 PEANUTS.md, 그리고 /egm-decide 트리플은 해당 스킬이 설치된 표면 매핑 위치에 보관하십시오. 채팅 기록은 아티팩트가 아닙니다.

절대 규칙: 절대 위반하지 마십시오

1. 읽기 전용입니다. 이 스킬이 작성하는 유일한 파일은 docs/egm/<slug>/DRIFT-REPORT.md입니다. 설계 문서, 코드, 테스트 또는 다른 원장(IMPLEMENT.md, GOLDFISH.md, ELEPHANT.md)을 절대 편집하지 마십시오. 제안된 업데이트를 적용하는 것은 사용자가 이후에 요청하는 별도의 요청입니다.
2. 증거가 없으면 드리프트가 아닙니다. 모든 항목은 문서가 말하는 내용(섹션 및 짧은 인용문)과 실제 구축된 내용(path:line, 또는 커밋, 또는 "해당 파일 없음")을 인용합니다. 양쪽에 증거가 없는 항목은 미해결 질문으로 나열됩니다.
3. 코드는 관찰된 사실이고, 문서는 주장입니다. 차이점을 중립적으로 보고하십시오. 원장이 결정을 기록하지 않는 한 어느 쪽이 옳은지 결정하지 마십시오. 제안된 업데이트는 평결이 아닌 제안입니다.
4. 신선한 시각이 비교를 수행합니다. 기능을 구현한 세션은 의도를 코드에 투영하여 읽는 편향이 있습니다. 가능할 때마다 비교를 신선한 읽기 전용 하위 에이전트(3단계)에 넘기십시오.

워크플로우

EGM 드리프트 보고서 진행 상황:
- [ ] 1단계: 설계 문서와 슬러그(slug) 확인됨; docs/egm/<slug>/ 발견됨
- [ ] 2단계: 기준 커밋 선택됨; 증거 팩 경로 나열됨
- [ ] 3단계: 신선한 읽기 전용 하위 에이전트(또는 인라인, 명시됨)에 의해 비교 실행됨
- [ ] 4단계: 발견 사항 확인, 분류 및 DRIFT-REPORT.md에 작성됨
- [ ] 5단계: 사용자에게 보고서 위치와 업데이트 적용 요청 가능함을 알림

1단계: 설계 문서 확인

사용자의 인수를 우선시합니다. 그렇지 않으면 프로젝트의 AGENTS.md 또는 CLAUDE.md에서 design_doc_path:로 명명된 폴더를 찾고, 거기에 없으면 docs/designs/*.md에서 찾습니다. 문서가 정확히 하나 있으면 그것을 사용하고, 여러 개 있으면 목록을 표시하고 어느 것인지 묻습니다. 슬러그는 .md 확장자를 제외한 문서 파일명이며, 상태 디렉토리는 docs/egm/<slug>/입니다. 해당 디렉토리가 존재하지 않으면 기능이 /egm-design을 거치지 않은 것입니다. 그렇게 말하고, 그래도 그곳에 보고서를 작성하겠다고 제안합니다(docs/egm/<slug>/DRIFT-REPORT.md만 생성).

2단계: 기준 선택 및 증거 팩 수집

기준은 문서가 승인된 시점입니다. 다음 중 첫 번째로 적용되는 것을 선택하고 사용한 기준을 기록합니다:

1. docs/egm/<slug>/GOLDFISH.md에서 human_review_gate: passed(또는 skipped-solo)를 설정한 커밋: git log --format='%H %ad %s' --date=short -- docs/egm/<slug>/GOLDFISH.md.
2. IMPLEMENT.md의 start_date 이전 또는 같은 날짜에 설계 문서를 마지막으로 변경한 커밋: git log --format='%H %ad %s' --date=short -- <doc>.
3. 사용자에게 커밋 또는 날짜를 요청합니다.

그런 다음 비교가 읽을 증거를 요약하지 않고 나열합니다:

• 설계 문서 (HEAD 기준, 기준 이후 변경된 경우 기준 시점의 버전: git show <base>:<doc>)
• docs/egm/<slug>/IMPLEMENT.md, 특히 ## Files touched, 모든 ## Drift 항목 (열림 및 해결됨) 및 ## Verification
• 문서 변경 사항을 기록한 GOLDFISH.md 처리 노트
• git log --stat <base>..HEAD 및 git diff --stat <base>..HEAD, 추가로 git status 및 git diff의 미커밋 변경 사항
• 문서의 상세 구현(Detailed Implementation)이 열거하는 파일 및 diff가 건드렸지만 문서에는 없는 파일

증거 팩에 포함되지 않는 것: 이 채팅, ELEPHANT.md 설계 추론, 또는 왜 그렇게 했는지에 대한 자신의 기억. 이것들은 원장이 명시하는 경우에만 "추정 이유" 열에 속합니다.

3단계: 신선한 읽기 전용 세션에서 비교 실행

Cursor에서 drift-auditor 유형의 Task 하위 에이전트 하나를 생성합니다(~/.cursor/agents/drift-auditor.md에 설치, readonly: true). 설치되어 있지 않으면 일반 Task 하위 에이전트를 사용하여 읽기 전용이라고 지시합니다. assets/drift-auditor-prompt.md의 프롬프트를 문서 경로, 슬러그, 기준, 증거 목록을 채워서 보냅니다. 다른 것은 추가하지 마십시오: 구현 요약, 변경 이유 설명은 포함하지 않습니다.

하위 에이전트 런타임이 없으면 동일한 프롬프트를 따라 직접 비교를 인라인으로 수행하고, 보고서 헤더에 comparison: inline (fresh subagent unavailable)을 기록하여 독자가 독립적이지 않았음을 알 수 있게 합니다.

4단계: 발견 사항 확인, 분류 및 보고서 작성

작성하기 전에 반환된 각 항목을 확인합니다: 인용된 path:line과 인용된 문서 섹션을 열고, 증거가 뒷받침하지 않는 것은 삭제하거나 수정합니다. 템플릿의 범주를 사용합니다: changed-approach, added, not-built, renamed-or-moved, interface-change, data-model-change, behavior-change, new-dependency, constraint-discovered, alternative-switched. 심각도는 major(문서가 시스템 작동 방식에 대해 독자를 오도할 수 있음), minor(세부 사항이 잘못됨), 또는 cosmetic(이름 지정, 표현)입니다.

IMPLEMENT.md와 상호 참조합니다: 각 항목을 logged(드리프트 항목이 존재하며 상태가 있음) 또는 unlogged로 표시합니다. 로깅되지 않은 주요 항목이 가장 중요합니다.

docs/egm/<slug>/DRIFT-REPORT.md를 assets/drift-report-template.md에서 작성합니다. 파일이 이미 존재하면, 파일 헤더 아래에 새 날짜 보고서를 맨 위에 넣고 이전 보고서들은 ## Earlier reports 아래에 변경 없이 그대로 둡니다. 이전 보고서를 절대 덮어쓰지 마십시오.

드리프트가 없으면, drift_items: 0, 사용된 기준 및 비교된 내용을 포함하여 보고서를 작성하여, "드리프트 없음"이 부재가 아닌 기록된 결과가 되도록 합니다.

5단계: 사용자에게 결과 전달

사용자에게 다음 형식으로 알립니다:

드리프트 보고서가 docs/egm/<slug>/DRIFT-REPORT.md에 작성되었습니다: 개 항목 (개 주요, 개 IMPLEMENT.md에 로깅되지 않음). 설계 문서나 코드를 변경하지 않았습니다. 문서가 구축된 것과 일치하도록 하려면 보고서에서 제안된 문서 업데이트를 적용하도록 요청하십시오. 기술 계획(Technical Plan)을 변경하는 항목은 /egm-design을 통해 다시 검토해야 하며, 대규모 재작성은 /egm-review를 통해야 합니다.

사용자가 보고서를 본 후 요청하지 않는 한, 이 세션에서 업데이트를 적용하지 마십시오.

안티 패턴

• 보고하면서 문서를 수정하는 것. 보고서가 결과물입니다. 문서를 편집하면 측정과 변경이 혼합되어 드리프트가 무엇인지 숨겨집니다.
• 문서에 맞추기 위해 코드를 수정하는 것. 반대 방향으로도 같은 문제입니다. 사용자가 어느 쪽을 움직일지 결정합니다.
• 기억으로 드리프트를 설명하는 것. 원장 항목 없이 "X 때문에 이것을 변경했습니다"라고 말하는 것은 추측입니다. reason: unknown이라고 쓰고 사용자가 채우도록 하십시오.
• 비교하는 대신 diff를 요약하는 것. 변경된 파일 목록은 드리프트 보고서가 아닙니다. 각 항목은 하나의 문서 주장을 하나의 관찰된 사실과 연결합니다.
• 시간을 절약하기 위해 신선한 세션을 건너뛰는 것. 구현 세션은 이미 코드가 문서와 일치한다고 믿습니다. 이 스킬이 존재하는 이유는 바로 그 믿음을 테스트하기 위함입니다.

EGM에서 이 스킬의 위치

/egm-learn(레거시 코드 전용) → /egm-design → /egm-review → /egm-implement → /egm-code-review, 그리고 /egm-implement 이후 언제든지 **/egm-drift-report**가 사용됩니다 (코드 리뷰 전후 모두).

• 읽기: 설계 문서, IMPLEMENT.md, GOLDFISH.md, 기준 이후의 git 히스토리, 코드.
• 쓰기: docs/egm/<slug>/DRIFT-REPORT.md만.
• 제공 대상: 이후의 "드리프트 보고서에서 설계 문서 업데이트" 요청; 기술 계획 변경을 위한 /egm-design; 업데이트된 문서의 재검증이 필요한 경우 /egm-review.