G1en-114/rtfm-first-skill

RTFM-First

사용자가 제공한 매뉴얼을 이 작업의 유일한 권위 있는 출처로 삼으십시오. 기억이나 인터넷 자료에 의존하여 코드를 작성하지 마십시오.

철칙

1. 매뉴얼이 존재하면, 코드를 작성하기 전에 먼저 매뉴얼을 읽으십시오; API 이름, 매개변수, 기본값, 단위, 동작은 모두 매뉴얼을 기준으로 합니다.
2. 코딩 전에 반드시 매뉴얼 버전과 현재 환경 버전을 대조하고('환경 스캔 및 버전 확인' 참조), 그 결과를 사용자에게 보고해야 합니다.
3. 매뉴얼의 핵심 사실을 인용할 때는 출처를 명시하십시오: .rtfm/<name>.txt:줄번호 또는 PAGE n.
4. 매뉴얼과 코드 또는 환경이 모순되는 경우, 즉시 코드를 인터넷 관행에 맞추어 '수정'하지 마십시오; 차이점을 설명하고 사용자에게 결정을 요청하십시오.
5. 매뉴얼이 없는 경우, 먼저 매뉴얼 경로를 요청하거나 확인하고, 기억에 의존하여 구현을 시작하지 마십시오.
6. '수정'을 수행하기 전에 반드시 위반된 매뉴얼의 조항을 지적할 수 있어야 합니다; 출처를 제시할 수 없으면 수정할 수 없습니다.

작업 흐름

1. 매뉴얼 찾기 및 추출하기

• 사용자가 경로를 제공하지 않은 경우, 프로젝트 내에서 후보(*.pdf, *.md, docs/**, README에 언급된 사양서)를 검색하십시오; 여러 후보가 있으면 나열하고 사용자에게 확인을 요청하십시오.
• 스크립트는 본 SKILL.md 파일이 있는 디렉토리의 scripts/ 하위에 있습니다.
• 프로젝트 루트 디렉토리의 .rtfm/ 디렉토리로 통일하여 추출하십시오 (git 저장소인 경우, .gitignore에 .rtfm/이 포함되어 있는지 확인하십시오):
  • PDF: 본 스킬의 scripts/extract_manual.py <manual.pdf> .rtfm/<name>.txt 실행
  • MD/TXT: 동일한 스크립트를 실행하면 텍스트 파일로 복사됩니다.
• 여러 매뉴얼(예: API 참조 + 프로토콜 사양 + SDK 문서)이 있는 경우, 모두 추출하고 각각 인덱스를 생성하십시오; 인용 시 어떤 매뉴얼인지 명시하십시오.
• PDF가 스캔 이미지인 경우(추출된 텍스트가 너무 짧은 경우), OCR이 필요하다고 보고하고, 내용을 억지로 추측하지 마십시오.
• 스크립트가 'PDF 텍스트 추출기 없음' 오류를 발생시키면, 안내에 따라 poppler-utils 또는 pypdf를 설치하고(시스템 수준 설치가 필요한 경우 먼저 사용자 동의를 얻음) 재시도하십시오; PDF를 건너뛰고 기억에 의존하여 작성하지 마십시오.
• 먼저 제목 페이지/서문/버전 기록을 읽고 다음을 기록하십시오: 제품명, 매뉴얼 버전, 적용 버전, 날짜, 개정 사항.

2. 인덱스 생성하기

• 본 스킬의 scripts/index_manual.py .rtfm/<name>.txt .rtfm/index.md를 실행하십시오.
• 어떤 주제든 찾을 때는 먼저 rg -n으로 인덱스와 본문을 검색하십시오; '기억에 없다'고 해서 매뉴얼에 없다고 생각하지 마십시오.

3. 환경 스캔 및 버전 확인

• 환경 증거를 수집하십시오: 매니페스트/잠금 파일(package.json, pyproject.toml, Cargo.lock, go.mod, requirements*.txt 등), --version/-V, pkg-config --modversion, 런타임 버전, SDK/툴체인/하드웨어 식별자.
• 매뉴얼 표지, 버전 기록, 바닥글, 메타데이터에서 매뉴얼 버전을 찾으십시오.
• references/version-matching.md에 따라 MATCH / COMPATIBLE / MISMATCH / UNKNOWN을 판정하십시오.
• 결론을 .rtfm/version-report.md에 기록하고 사용자에게 보고하십시오.
• MISMATCH 또는 UNKNOWN인 경우 멈추십시오: 사용자에게 일치하는 버전의 매뉴얼을 제공하거나 명시적으로 계속 진행을 승인받도록 요청하십시오; 승인 후에는 위험을 notes에 기록하십시오.

4. 매뉴얼에 따라 코드 작성하기

• 각 컴포넌트/API를 작업하기 전에 관련 섹션을 완전히 읽으십시오; 핵심 시그니처, 상수, 기본값, 경계 조건을 .rtfm/notes.md에 출처와 함께 발췌하십시오.
• .rtfm/notes.md 제안 구조: 매뉴얼 이름과 버전, 버전 확인 결론(MATCH/COMPATIBLE/MISMATCH/UNKNOWN), 주제별 발췌(각 항목에 manual.txt:L줄 또는 PAGE n 포함), 수정 기록.
• 식별자, 문자열, 숫자는 매뉴얼 원문에서 복사하여 필사 과정에서 오타가 발생하지 않도록 하십시오.
• 매뉴얼이 다루지 않는 부분에는 TODO + 출처('매뉴얼 특정 섹션에 설명 없음')를 표시하고, 조용히 인터넷 자료로 보충하지 마십시오; 실제로 보충이 필요한 경우 먼저 사용자 동의를 구하십시오.
• 매뉴얼이 말한 것이 곧 법칙입니다: 인터넷의 '모범 사례'와 다르더라도, 사용자가 요청하거나 빌드/테스트 증거가 매뉴얼과 현재 환경이 일치하지 않음을 입증하지 않는 한, 코드를 인터넷 버전으로 반복해서 '수정'하지 마십시오.

5. 검증 및 마무리

• 완료 후 매뉴얼의 각 섹션을 대조하여 자체 점검하십시오: 사용된 모든 API/설정/동작이 notes에서 출처를 찾을 수 있어야 합니다.
• 빌드/테스트를 실행하십시오; 실패 시 먼저 매뉴얼 관련 섹션에서 근거를 찾은 다음 환경을 확인하고, 추측은 금지됩니다.
• 인도 시 간략히 다음을 나열하십시오: 매뉴얼 버전, 환경 버전, 확인 결론, 주요 출처, 사용자 확인이 필요한 모든 차이점.

수정 루프 방지

본 스킬이 존재하는 직접적인 이유: AI가 매뉴얼을 읽지 않음 → 인터넷 기억에 의존하여 코드를 '수정'함 → 또 틀림 → 다시 수정, 반복적 재작성. 다음 규칙을 준수해야 합니다:

• 수정 전에 증명하십시오: 코드/설정을 변경할 때마다 먼저 '현재 구현이 매뉴얼의 몇 번째 줄을 위반하는지' 지적하고 출처를 인용하십시오; 출처를 제시할 수 없으면 수정할 수 없습니다.
• 한 번에 하나의 원인만 수정하십시오: '보기에 좋지 않음'과 '매뉴얼 불일치'를 하나의 수정에 혼합하지 마십시오; 관련 없는 코드는 원래 상태로 유지하십시오.
• 동일한 현상이 두 번 수정된 후에도 여전히 발생하는 경우: 패치를 중단하고 매뉴얼로 돌아가 관련 섹션을 완전히 다시 읽고, 자신의 이해를 의심하십시오; 계속 추측하지 마십시오.
• 매뉴얼 동작이 인터넷 관행과 충돌하는 경우: 매뉴얼을 기준으로 하십시오; '실행은 되지만 매뉴얼에 부합하지 않는' 코드를 인터넷 버전으로 변경하지 말고, 그 반대도 마찬가지입니다.
• 오류 발생 시 먼저 매뉴얼을 확인하십시오: 오류 코드, 제약 조건, 경계 조건 섹션을 확인하십시오; 매뉴얼에 해당 항목이 없는 경우, 환경 증거를 확인하고 직관에 따라 변경하는 것을 금지합니다.
• 수정할 때마다 .rtfm/notes.md의 수정 기록에 한 줄을 추가하십시오: 대상, 변경 내용, 근거 출처. 두 라운드의 수정 후에도 올바르지 않으면, 먼저 기록을 대조하여 중복을 찾으십시오.