Ephasme/refine-document

문서 정제 (Refine Document)

하나의 문서를 가져와 프로젝트에 대한 사전 지식이 없는 독자가 바로 사용할 수 있는 버전을 생성합니다: 레거시 없음, 사실 기반, 간결, 조직적, 선언된 독자에 맞춤.

네 개의 패스, 고정된 순서, 그 다음 검증 게이트. 제거된 모든 내용은 기록 파일에 기록되므로 잘못된 호출도 복구 가능합니다.

호출 방법

refine-document <path> [--target=agent|human] [--no-record]

플래그	기본값	효과
--target	agent	마지막 패스가 최적화할 독자. 문서 자체를 변경합니다. 어조만 바꾸는 것이 아닙니다 — 패스 4 참조.
--no-record	꺼짐	기록 파일을 건너뜁니다. 제거 내용은 버전 관리 외에는 복구할 수 없게 됩니다.

파일을 건드리기 전에:

1. 요청이 이 문서를 명명했는지 확인하십시오. 이것은 사용자의 파일을 제자리에서 다시 씁니다.
2. 파일이 버전 관리에서 추적되고 깨끗한지 확인하십시오. 그렇지 않으면 말하고 명시적인 승인을 받으십시오 — --no-record 아래에서 그것이 유일한 복구 경로입니다.
3. 실행 중인 대상을 첫 번째 메시지에 명시하십시오. 기본값일 때도 포함합니다. 묵시적 기본값은 문서가 잘못된 독자용으로 형성되는 방법입니다.
4. 여러 문서: 각 문서에 대해 이 절차를 한 번 실행하고, 하위 에이전트를 사용할 수 있는 경우 각각 하나의 하위 에이전트를 사용하며, 동일한 대상과 플래그를 모두에게 전달합니다. 하위 에이전트는 정확히 하나의 파일을 소유합니다.

출력

출력	경로	내용
정제된 문서	원래 경로, 제자리	현재 상태만, 대상에 맞춰짐
기록	{name}.changelog.md, 같은 디렉토리	제거된 모든 내용, 그대로, 위치 포함 — 실행 간에 추가 전용
보고서	당신의 응답	보고서 참조

패스 순서

이 순서대로 패스를 실행하고, 문서를 네 번 별도로 읽습니다. 각 패스는 다음 패스의 입력을 줄이며, 순서가 잘못되면 서로를 취소합니다 — 패스 1이 삭제할 산문을 압축하는 것은 작업을 낭비하고, 패스 4 전에 정리하면 내용을 정리합니다.

1. 레거시 제거 — 과거에 대한 참조로만 의미가 있는 모든 것을 제거합니다.
2. 사실 확인 — 살아남은 모든 주장을 확인, 인용, 또는 표시합니다.
3. 간결화 — 하나의 사실, 하나의 장소, 사실을 유지하는 가장 짧은 형태.
4. 조직화 — 중요한 것 먼저, 그 다음 대상의 형태.

패스 1 — 레거시 제거

필수 하위 스킬: 이 패스에는 strip-legacy-content를 사용하십시오. 그것은 레거시 분류 체계, 제거-하지-않고-다시-쓰기 규칙, 그리고 이 스킬도 작성하는 {name}.changelog.md 형식을 소유합니다. --no-record를 --no-changelog에 매핑하십시오.

해당 스킬을 사용할 수 없는 경우, 제거: 기록 및 진화 내러티브, 결정 기록 및 ADR, 지원 중단 알림, 마이그레이션 및 업그레이드 가이드, 포함된 변경 로그 및 릴리스 노트, 하위 호환성 섹션, 거부된 대안, 날짜가 있는 논평, 대체된 섹션. 범위를 제거하십시오; 살아남은 산문을 다시 쓰지 마십시오 — 패스 2-4가 처리합니다.

지원 중단 기능 규칙. 지원 중단으로 표시된 기능은 자동으로 레거시가 아닙니다. 이 테스트를 적용하고, 어떤 분기를 선택했는지 기록하십시오:

이 기능에 "이전 시스템 지원"이 아닌 용도가 있습니까?

• 아니오 — 하위 호환성만을 위해 존재합니다. 기능과 알림을 제거하십시오.
• 예 — 현재 동작입니다. 유지하고, 제거 일정과 "v1 이후" 프레임을 삭제하고, 기록에 플래그를 지정하십시오.

패스 2 — 사실 확인

문서가 만드는 모든 주장은 클레임이며, 상속된 것도 포함합니다. 각각을 분류하고 일치하는 조치를 취하십시오. 다섯 번째 옵션은 없습니다.

클래스	신호	조치
확인 가능, 아티팩트 접근 가능	동작, 플래그, 기본값, 경로, 명령어, 구성 키이며 코드, 구성 또는 --help를 읽을 수 있음	확인하십시오. 참: 유지. 거짓: 수정.
확인 가능, 아티팩트 접근 불가	동일한 클레임, 리포지토리, 바이너리, 또는 확인할 문서 없음	소스가 명시한 대로 클레임을 표시 없이 정확히 유지하고, 보고서에 확인되지 않은 것으로 나열하십시오.
외부 출처 가능	표준, 프로토콜 동작, 타사 제품 동작, 버전 지원	인라인으로 주요 출처를 날짜 또는 버전과 함께 인용하십시오. 허용되는 출처 없음: 클레임을 삭제하십시오.
비교 또는 홍보	"10배 빠름", "최고 수준", "눈부신", "우아한", "대부분의 엔지니어가 동의함", 그리고 다른 용어가 현재 시스템의 일부가 아닌 비교("Kafka보다 가벼움")	삭제하십시오. 단, 인용 가능한 측정값이 있는 경우 제외 — 그런 다음 측정값과 출처를 명시하십시오. 살아남은 사실은 유지: "Redis Streams로 작업 대기열".
확인 불가능하고 위험함	독자가 돌이킬 수 없는 조치를 취할 수 있는 확인되지 않은 클레임: 데이터 손실, 지출, 자격 증명, 파괴적인 명령어, 보안 경계	유지하고, 문서에 [unverified]로 표시하고, 보고서에 나열하십시오.

표시는 출처가 아니라 위험을 위한 것입니다. 접근할 수 없는 아티팩트에 대한 문서는 대부분 확인되지 않은 클레임이며, 각각을 표시하면 독자가 표시를 건너뛰도록 가르칩니다. 확인되지 않은 출처는 보고서와 기록에 속합니다; 문서의 [unverified]는 독자가 취소할 수 없는 실패를 위한 것입니다. 소수 이상의 표시가 문서에 남아 있으면 출처를 위험으로 분류한 것입니다 — 재분류하십시오.

출처 문서에 없었던 사실을 절대 발명하지 마십시오. 구성 위치, 기본값, 파일 형식, 전제 조건 — 거의 확실히 사실인 것조차도 마찬가지입니다. 평평하게 명시된 추론된 사실은 확인된 사실과 구별할 수 없으며, 이 패스가 독자와 자신 있는 잘못된 답변 사이에 있는 유일한 것입니다. 출처가 침묵하면 정제된 문서도 침묵합니다.

출처 없는 클레임을 더 모호한 것으로 절대 부드럽게 만들지 마십시오. "대략 10배 빠름"을 "매우 빠름"으로 다시 쓰는 것은 덜 정밀한 동일한 의견입니다. 인용하거나 삭제하십시오.

출처 부족으로 운영 지침을 절대 삭제하지 마십시오. 표시가 삭제보다 낫습니다: 표시된 지침은 아는 사람이 확인할 수 있지만, 삭제된 것은 사라집니다.

클레임이 대부분 외부인 문서의 경우, 계속하기 전에 출처 확인을 위해 cite-or-refuse를 실행하고 전체 클레임 감사를 위해 fact-check-document를 실행하십시오.

패스 3 — 간결화

하나의 사실, 하나의 장소. 각 사실에 대해, 그것을 찾는 독자가 먼저 도착할 단일 섹션을 선택하십시오. 거기에 완전히 명시하십시오. 다른 곳에서는 반복을 삭제하거나 해당 섹션을 정확히 명명하는 포인터로 바꾸십시오.

직접 삭제:

• 채우기 도입부: "주목할 가치가 있는 것은", "단순히", "기본적으로", "보시다시피".
• 독자가 이미 하고 있는 일을 하라는 지침: "설치하려면 설치 명령어를 실행하십시오".
• 첫 문장으로 반복된 섹션 제목.
• 동작을 변경하지 않는 방어적 단서.
• 이전 예제와 동일한 것을 보여주는 예제.

압축:

• 두 개 이상의 속성에 대해 세 개 이상의 항목 비교 → 표.
• 병렬 항목을 나열하는 단락 → 목록.
• 주어가 명사화된 문장 → 동사("결정을 내리다" → "결정하다").

압축 한계. 다음 단어를 제거할 때 사실이 제거되면 멈추십시오. 사실을 잃은 더 짧은 문서는 진보가 아니라 회귀입니다. 단어 수는 작업의 증상일 뿐, 목표가 아닙니다.

하나의 조건부 허용 중복은 패스 4에서 설정된 길이 임계값을 초과하는 에이전트 대상의 머리와 꼬리 반복인 중요 블록입니다. 그 임계값 아래에서는 다른 반복과 마찬가지로 제거됩니다.

패스 4 — 선언된 독자에 맞게 조직화

공통: 순서 법칙

주제의 역사가 아니라 독자를 차단하는 것에 따라 순서를 정하십시오:

1. 이것이 무엇인가 — 한 문장, 서문 없이.
2. 다른 모든 것을 차단하는 전제 조건 — 그것 없이는 아무것도 시작되지 않는 환경 변수, 자격 증명, 필수 버전.
3. 파괴적이고 되돌릴 수 없는 작업 — 삭제, 덮어쓰기, 비용 지출, 또는 취소할 수 없는 모든 것. 이것은 주제가 아니라 결과에 따른 배치입니다: 명령어가 모호하더라도 상단 근처에 가며, 단순히 언급되는 것이 아니라 표시됩니다.
4. 주 경로 — 대부분의 독자가 하러 온 일, 처음부터 끝까지.
5. 기타 모든 것, 가장 많이 사용되는 것부터.
6. 에지 케이스, 문제 해결 및 참조 표 마지막.

문서에 약 5개 섹션 이상이 있는 경우 상단에 요약 블록이 속합니다; 산문의 개요가 아니라 독자가 무언가를 하기 전에 알아야 할 사실을 나열합니다.

--target=agent

독자는 문서를 컨텍스트로 로드하는 모델이며, 종종 하나의 용어를 검색하고 일치하는 부분만 읽습니다. 이 모양의 문서를 생성하십시오:

1. 항상 먼저 중요 블록; 약 100줄을 넘는 경우에만 마지막에 동일한 블록을 그대로 반복. 전제 조건, 파괴적인 작업 및 하드 제약 조건은 길이에 관계없이 먼저 갑니다. 중간에서의 손실 저하(Liu et al., TACL 2024)는 수천에서 수만 토큰 범위의 다중 문서 컨텍스트에서 측정됩니다 — 한 번에 읽을 수 있을 만큼 짧은 문서에는 그 의미에서 "중간"이 없으며, 거기에 꼬리 복사본은 검색 이점 없이 순수한 중복입니다. 문서가 내용 목록(#9 아래)을 얻는 동일한 약 100줄 임계값을 넘을 때만 복제하십시오. 여기서 검색-및-조각 읽기가 문서 중간에 도착하여 블록을 놓칠 수 있습니다. 임계값 아래에서는 상단에 한 번 명시하고 멈추십시오 — 거기에 두 번째 복사본은 패스 3이 잡았어야 할 회귀이며, 이 대상의 기능이 아닙니다. 정당한 경우: 첫 번째 복사본에 ## Critical constraints 제목을, 마지막에 ## Critical constraints (repeat) 제목을 붙이십시오 — 두 개의 고유 앵커, 하나의 동일한 본문, 문서가 포함할 수 있는 유일한 거의 중복 제목입니다.
2. 긍정적 표현. 취할 조치를 명시하십시오. 금지가 진정으로 필요한 경우, 같은 문장에 긍정적 대안을 넣으십시오: "state/에 쓰고, /tmp에는 쓰지 마십시오". 모델은 부정된 문장을 긍정적인 문장보다 눈에 띄게 더 나쁘게 처리합니다.
3. 하나의 제목, 하나의 검색 가능한 단위. 모든 제목은 문서 내에서 고유하고, 문자 그대로이며, 에이전트가 검색할 단어로 구성됩니다 — 위의 중요 블록 쌍은 제외. 해당 섹션은 독립적입니다: "위에서 설명한 대로", 다른 섹션의 선행사를 가진 대명사가 없습니다.
4. 사용 지점에서의 리터럴 식별자. 전체 경로, 정확한 명령줄, 정확한 환경 변수 이름, 정확한 파일 이름 — 매번, 참조 후가 아니라.
5. 내러티브보다 확인 가능한 진술. 명령어, 경로, 값, 종료 조건. 문장을 확인할 수 없으면 아마도 근거일 것입니다 — 에이전트가 하는 일을 변경하는 경우에만 유지하십시오.
6. Markdown 구조만 — 제목, 목록, 코드 블록, 작은 표. Markdown 문서에 XML 태깅 체계를 추가하지 마십시오; 진정한 기계 판독 데이터인 콘텐츠에 대해 JSON 또는 YAML 블록을 예약하십시오.
7. 모든 사실을 유지하는 가장 짧은 형태. 입력 길이는 그 자체로 검색을 저하시키며, 아무 것도 답하지 않는 주제적으로 인접한 콘텐츠는 방해 요소로 작용합니다 — 거의 일치하는 산문은 부재보다 나쁩니다.
8. 모순 없음. 동의하지 않는 두 진술은 어느 쪽도 없는 것보다 나쁩니다. 쓰기 전에 해결하십시오.
9. 약 100줄을 넘는 경우에만 내용 목록, 에이전트가 전체 파일이 아닌 조각을 읽을 수 있고 그렇지 않으면 범위를 볼 수 없기 때문입니다.

수용 기준: 하나의 제목을 검색하고 해당 섹션만 읽는 에이전트가 올바르게 행동합니다.

--target=human

독자는 읽기 전에 스캔하고 단어의 소수를 읽습니다. 형식이 단서를 제공하지 않으면, 그 스캔은 왼쪽 가장자리를 따른 F자형 스윕으로 저하됩니다 — 구조는 그것을 방지하는 것이지, 모방하는 것이 아닙니다. 이 모양의 문서를 생성하십시오:

1. 문서와 모든 섹션의 첫 문장에 요점. 처음 두 단락에 가장 중요한 내용; 거기서 멈추는 독자는 필요한 것을 얻었습니다.
2. 앞으로 적재된 줄. 모든 제목, 글머리 기호 및 단락은 정보를 전달하는 단어로 시작합니다 — 줄의 처음 두 단어는 읽히고, 나머지는 스캔됩니다.
3. 설명적인 제목: "상태 디렉토리 구성", 절대 "개요", "참고", "세부 사항" 또는 "섹션 3".
4. 단락당 하나의 아이디어, 대략 최대 4문장.
5. 객관적인 언어. 중립적인 표현은 가독성을 위해 홍보적인 표현보다 눈에 띄게 더 나은 성과를 냅니다; 이것은 스타일 선호도가 아니라 이해도 결과입니다.
6. 비교는 표, 추론은 산문. 두 개 이상의 속성에 대해 세 개 이상의 항목 → 표. 연결된, 인과적 또는 미묘한 설명은 산문으로 유지 — 논증을 글머리 기호로 조각내면 연결이 손실됩니다.
7. 도메인 어휘 유지. 용어를 처음 사용할 때 인라인으로 한 번 정의하십시오. 기술적 정밀도를 단순화하지 말고, 가독성 공식 점수 쪽으로 다시 쓰지 마십시오 — 그 점수는 조직을 볼 수 없고 올바른 용어를 불이익합니다.
8. 약 2화면 또는 5개 섹션을 넘는 경우 내용 목록.

수용 기준: 독자가 문서만 사용하여 문서가 설명하는 작업을 완료할 수 있습니다.

대상 간에 달라야 하는 것

결정	--target=human	--target=agent
중요 제약 조건	첫 화면에 한 번, 표시	~100줄 미만에서 상단에 한 번; 그 이상에서는 첫 번째 및 마지막에 그대로 반복
섹션 독립성	섹션이 이전 섹션을 기반으로 할 수 있음	모든 섹션이 자체 포함
상호 참조	"위 참조" 괜찮음	정확한 제목 명명
제목	설명적이고 읽기 쉬움	고유, 문자 그대로, 검색에 적합
금지	"X를 하지 마십시오" 괜찮음	"Y를 하십시오"가 금지를 전달
식별자	한 번 도입한 후 축약 가능	매번 전체이고 문자 그대로
추론	산문이 인과 관계 유지	조치를 변경하는 경우에만 유지
내용 목록	~2화면 이상	~100줄 이상
길이	원래 단어의 약 절반	모든 사실을 유지하는 가장 짧은 형태

차이 검사 — 필수. 파일을 쓰기 전에, 이 실행이 선언된 대상 때문에 다르게 만든 적어도 세 가지 결정을 명명하고 보고서에 넣으십시오. 예를 들어:

대상이 agent였기 때문에:

1. "디렉토리가 존재하는지 확인하십시오"를 os.path.isdir(path)로 바꾸었습니다 — 에이전트가 실행할 수 있는 명령어.
2. 문서 끝에서 반복되는 중요 제약 조건 블록을 ~120줄에서 추가했습니다.
3. 제목을 agent.md에서 agent (target)으로 변경했습니다 — 에이전트가 --target=agent를 검색할 수 있도록.

보고서

매번, 당신의 응답에 이 구조를 반환하십시오:

섹션	내용
요약	패스당 한 문장. 제거된 줄 수, 확인/수정된 사실, 압축 비율.
차이	— 레거시: type:readme-preamble — 프로젝트 시작에 대한 3줄을 "동기"로 제거했습니다. — 사실: 특성 — WM_CONCAT은 Oracle 12c 이후 지원되지 않습니다. 수정: LISTAGG. 출처: Oracle SQL 언어 참조 v12.2. — 간결화: 압축: 부록 A의 4개 예제를 하나로 병합했습니다. — 조직: 재배치: 경고를 스크립트 블록 바로 위로 이동.
대상 차이	(필수) 선언된 대상 때문에 다르게 한 세 가지 결정. 위 형식 참조.
벨 카브	미해결 문제 (마킹된 확인되지 않은 위험, 보류된 삭제, 불완전한 출처 확인, 의견 불일치). 확인 표시가 있는 동의한 동료 검토 — 필수, 실행당 적어도 하나.

추가 정보

이 스킬에 관해. refine-document는 문서를 원래보다 짧고 조직적으로 만들고, 모든 주장을 확인하며, 레거시 특성을 제거하고, 선언된 독자의 필요에 맞춥니다. 에이전트 대상은 LLM 컨텍스트 창에 맞게 최적화되고, 인간 대상은 빠른 스캔 및 이해에 최적화됩니다.

제한 사항: 이 스킬은 접근 가능한 출처(코드, 구성, 도움말 출력)와의 사실 확인에 의존합니다. 출처 문서에 없는 사실을 발명하지 않습니다. 외부 소스는 인라인으로 인용해야 합니다.

종속성: strip-legacy-content 하위 스킬 (패스 1 필수). 선택적: cite-or-refuse 및 fact-check-document (패스 2).