name: editorial-pass description: Review a finished or near-finished document the way a human editor reads it, start to finish, building a model of what it's trying to communicate, then diagnosing cohesion, coherence, narrative throughline, pacing, consistency, reading fluency, contextualization, and clarity across the whole piece, never just line-by-line. Also hunts four noise categories agents habitually leave behind: provenance narration ("as verified in X", "so-and-so confirmed"), ruled-out-hypothesis residue ("we confirmed it is not Y"), self-referential scaffolding, and dramatized background (illustrating known concepts, stakes-selling, deriving what only needs asserting). Use whenever the user asks to review, edit, polish, tighten, or clean up a document, asks whether a doc "reads well", "flows", "makes sense", or "has a throughline", or before shipping any long-form prose another human will read: TDDs, RCAs, design docs, investigation writeups, READMEs, proposals, long PR descriptions.
에디토리얼 패스은(는) 무엇을 하나요?
에이전트는 린터(linter)가 코드를 검토하는 방식으로 문서를 검토합니다. 한 번에 하나의 국소적 문제를 찾고, 각각을 규칙에 따라 판단하며, 전체에 비추어 판단하지 않습니다. 인간 편집자는 다릅니다. 문서를 처음부터 끝까지 읽고, 무엇을 전달하려는지에 대한 실행 모델을 구축한 다음, 그 모델이 혼란스러워지거나 지루해지거나 길을 잃는 지점을 발견하고, 그 후에야 라인 수준으로 내려갑니다. 문서를 실패하게 만드는 요소의 대부분은 라인 수준에서는 보이지 않습니다. 아무도 묻지 않은 질문에 답하는 섹션, 중간에 의미가 바뀌는 용어, 하나의 아이디어를 세 문단에 걸쳐 반복해서 늘어지는 중간 부분, 서두에서 하지 않은 약속을 끝에서 이행하는 결말 등입니다.
이 스킬이 바로 그 편집자입니다. 기술 문서든 아니든 모든 장문의 문서에 적용됩니다. TDD와 에세이를 다른 종류로 취급하지 마십시오. 인간은 둘 다 잘 구성된 단계, 이해관계, 그리고 그에 따른 결과를 통해 처리합니다. 모두 스토리텔링이며, 편집자의 임무는 모든 곳에서 동일합니다. 문서가 전달하려는 바를 독자가 얻는 과정에서의 위험과 인지적 부하를 최소화하는 것입니다. 기술 문서의 경우, 독자가 다시 읽지 않고도 무엇을 해결하는지, 왜, 어떻게에 답할 수 있음을 의미합니다.
무엇보다도 먼저 한 가지 경계를 긋겠습니다: 이것은 산문 편집자이지 기술 검토자가 아닙니다. 글쓰기를 검토하며, 글이 설명하는 작업을 검토하지 않습니다. 스키마가 올바른지, 설계가 타당한지, 숫자가 맞는지는 다른 사람의 검토 영역입니다. 당신의 관할 구역은 독자가 문서가 말하는 바를 수용할 수 있는지 여부입니다. 유일한 예외는 내부 모순입니다. 문서가 스스로와 모순될 때, 이는 글쓰기 결함이며 당신이 지적해야 할 사항입니다.
호출 시기
문서가 존재하고 사람이 읽을 예정일 때마다: 사용자가 검토, 편집, 다듬기, "이해가 되나" 확인, 또는 당신이나 다른 사람이 작성한 초안 정리를 요청할 때입니다. 장문의 문서 초안 작성을 완료한 후에는 사전에 적극적으로 호출하십시오. 아래의 실패 패턴은 정확히 초안 작성 에이전트가 도입하는 패턴이기 때문입니다. 문서를 처음부터 작성하는 경우, /flagrare:write-docs가 기술을 담당하고 /flagrare:tdd-writer가 TDD를 담당합니다. 이 스킬은 읽기 및 수정 대응편이며 초안이 이미 존재한다고 가정합니다.
계약: 먼저 편집 메모를 생성(5단계)하고, 작성자의 승인을 받은 후에 적용하십시오. 문서를 조용히 1단계로 다시 쓰지 마십시오.
절차
1. 전체 문서를 읽습니다. 두 번.
단 하나의 메모도 작성하지 않고 전체 문서를 먼저 읽으십시오. 첫 번째 읽기는 검토자가 아닌 대상 독자로서의 느낌 경험을 위한 것입니다. 어디서 집중했는지, 어디서 주의가 분산되었는지, 어디서 되돌아가 다시 읽어야 했는지, 무엇을 해결되지 않은 채 얼마나 오래 머리에 담고 있어야 했는지. 첫 접촉에서 주석을 달고 싶은 충동을 억제하십시오. 많은 명백한 문제는 문서 후반부에서 해결되며, 많은 실제 문제는 회고적으로만 보입니다.
첫 번째 읽기가 끝나면 한 문장을 쓰십시오: 이 문서는 무엇을 전달하려고 하는가? 그 문장이 핵심입니다. 검토의 다른 모든 것은 이것에 달려 있습니다. 그 문장을 쓸 수 없다면, 그 무능력이 주요 발견 사항이며 라인 수준의 어떤 것도 아직 중요하지 않습니다.
두 번째 읽기는 진단입니다. 이제 문서가 무엇을 하려는지 알았으므로, 질문은 다음과 같습니다: 어디에서 성공하고, 어디에서 부족한가?
2. 큰 것에서 작은 것으로 진단
구조가 흐름보다 먼저, 흐름이 문단보다 먼저, 문단이 라인보다 먼저입니다. 문서의 아치(arc)가 깨졌을 때 쉼표 남용으로 여는 편집 메모는 작성자의 주의를 낭비합니다. 네 가지 계층을 아래로 내려가며 작업하십시오:
흐름선(Throughline). 모든 섹션이 핵심을 뒷받침하는가, 아니면 일부 섹션은 다른 문서에 속하는가? 서두는 문서의 나머지 부분이 유지하는 약속(질문, 이해관계, 갈고리)을 하는가? 두 가지 저렴한 전체 문서 프록시: 제목만 순서대로 읽고 훑어보는 독자가 그들만으로 논증을 재구성할 수 있는지 확인하십시오. 그런 다음 각 문단의 첫 번째 문장만 읽고 그것들만으로 일관된 체인을 형성하는지 확인하십시오. 어느 체인이든 끊어지면, 문장이 무엇을 말하든 구조가 거기서 깨진 것입니다.
순서 및 맥락화. 독자는 이전 문장이 준 것만으로 문장을 이해할 수 있습니다. 각각의 새로운 개념, 주장 또는 용어에서 문서를 훑으며 질문하십시오: 독자가 이것을 여기서 받아들일 수 있도록 필요한 것이 제공되었는가? 맥락은 필요 시점에 제공되어야 하며, 용어집이나 세 섹션 뒤에가 아닙니다. 가장 흔한 실패는 저주의 지식 순서입니다. 작성자는 자신이 배운 순서나 시스템이 실행되는 순서로 내용을 제시하며, 낯선 사람이 흡수할 수 있는 순서가 아닙니다.
속도 및 비율. 문서의 공간은 강조입니다. 각 아이디어가 받는 텍스트 양이 핵심에 대한 중요성과 일치하는가? 두 가지 표준적인 실패는 반대입니다: 하중을 지탱하는 위험이 하나의 긴 문장에 압축되고, 사소한 메커니즘이 작성자가 알아내는 재미를 느꼈기 때문에 세 문단에 걸쳐 펼쳐지는 경우. 또한 늘어지는 중간 부분(연속된 섹션이 하나의 아이디어를 다른 옷으로 반복), 그리고 반복 정보(동일한 사실이 두 번 소개되면 일반적으로 두 개의 초안이 병합되었고 아무도 전체를 다시 읽지 않았음을 의미)를 주시하십시오.
일관성. 전체 문서에 대해 개념당 하나의 이름; 동의어 순환은 작성자에게는 우아한 변주로 읽히지만 독자에게는 두 번째 개념으로 읽힙니다. 섹션 간에 숫자, 주장 및 용어가 일치하는지, 약속된 것("아래에서 논의됨")이 누락되지 않았는지, 문서 중간에 어조가 갑자기 바뀌지 않는지 확인하십시오.
3. 네 가지 잡음 범주 사냥
이것들은 삭제 작업입니다. 에이전트(및 피곤한 인간)는 세 가지를 모두 남깁니다. 각각은 작성 과정의 잔재가 출하된 문서에 드러난 것입니다. 독자는 건물을 사는 것이지 발판을 사는 것이 아닙니다.
출처 서술(Provenance narration). 작성자가 사실을 어떻게 알게 되었는지는 연구 경로이지 내용이 아닙니다. "ia-logic.js에서 확인됨", "X가 스레드에서 Y와 확인함", "설계 문서가 여기를 가리킴", "코드, Confluence 및 Slack을 확인했지만 해당 작업이 없음". 사실을 진술하고 그것이 스스로 권위를 갖도록 두십시오. 검증은 이루어졌지만 서술될 필요는 없습니다. 주의할 단어: verified, confirmed, as discussed with, per the thread, according to the doc, after checking, I looked at.
이전: M1 결정 문서(PM이 2026-06-16 스레드에서 확인함)에 따라
sold_out은 자정 장소 현지에서 재설정되어야 합니다. 코드, Confluence 및 Slack을 확인한 결과 오늘날 그러한 재설정 작업은 존재하지 않습니다.이후:
sold_out은 자정 장소 현지에서 재설정되며, 오늘날 이를 수행하는 작업이 없으므로 "내일까지 품절"로 표시된 항목이 지워지지 않습니다.
두 가지 예외, 둘 다 좁은 범위입니다. 사람의 서명이 보류 중인 조치(승인자, 미해결 결정의 소유자)일 때만 사람을 인용하고, 사실의 귀속으로 사용하지 마십시오. 방법이 주장 그 자체일 때만 방법을 유지하십시오: 벤치마크 결과는 측정 방법과 분리할 수 없습니다.
기각 가설 잔재(Ruled-out residue). 에이전트는 자신이 증명한 내용 주변의 부정적 공간에 대한 기록을 유지합니다: "우리는 조정이 원인이 아님을 확인했습니다", "이것은 헛다리였음이 밝혀졌습니다", "서빙 경로에 대한 변경이 필요하지 않음(확인됨)". 조사에는 그 단계가 필요했습니다. 독자는 거의 항상 필요로 하지 않습니다. 죽은 가지는 미래의 독자가 그럴듯하게 같은 막다른 골목에 들어가 작업을 반복할 경우에만 한 문장을 받을 자격이 있으며, 그런 다음에도 독자가 파고들기 시작할 바로 그 지점에 한 줄로 배치되고 자체 섹션을 갖지 않습니다. 그 외의 모든 것: 긍정적인 결론을 유지하고, 반증을 삭제하십시오. "이 기능은 쓰기 경로입니다. 읽기는 이미 작동합니다"라는 한 문장이 "변경 불필요(확인됨)" 전체 섹션이 하던 일을 수행합니다.
자기 참조적 발판(Self-referential scaffolding). 문서가 초안으로서 자신에 대해 이야기하는 것: "이것은 이전 메모를 수정합니다", 확인된 사항에 대한 오래된 [확인 필요] 표시, 해결된 질문을 취소선 항목과 "해결됨:" 주석으로 유지, 확인된 모든 출처를 나열하는 마무리 "검증 요약". 결정된 사항은 질문이 아닙니다: 선택 사항을 한 번, 그것이 속한 곳에 명시하고, 논의를 삭제하십시오. 헤딩 아래 모든 것이 해결되었다면 "해당 없음"을 쓰지 말고 헤딩을 자르십시오. 이 범주가 존재한다는 신호: 문제를 해결한 과정에서 문서가 길어졌다는 것입니다. 이후 과정은 빼야 합니다.
극화된 배경(Dramatized background). 독자가 받아들이기만 하면 되는 것에 대해 논쟁하는 글. 세 가지 신호: 방이 이미 알고 있는 개념에 대한 설명("'햄버거'는 '소스를 선택하세요' 옵션이 없는 고정된 하나의 항목입니다"); 문서의 존재 자체가 이미 중요성을 확립했을 때 그 중요성을 판매하는 이해관계 문장("사용자 정의가 진정한 메뉴를 만드는 것입니다"); 그리고 그 결론만 다운스트림에서 사용되는 인과 관계 체인을 단계별로 설명하는 경우("유일한 작성자는 POS 동기화입니다. 수동 파트너는 POS가 없습니다. 따라서 저작할 수 없습니다"). 독자의 고도에서 사실을 주장하고 넘어가십시오. 메커니즘을 한 번, 그것이 하중을 지탱하는 곳에서 명시하고, 서론에서가 아닙니다. 이 삭제가 실제 맥락을 훼손하지 않도록 하는 경계: 맥락은 결정을 위한 것이고, 주장은 배경을 위한 것입니다. 독자가 판단해야 하는 모든 것은 전체 재료(현재 동작, 분기점, 이해관계)를 유지합니다. 독자가 계속 읽기 위해 단순히 받아들여야 하는 모든 것은 평범한 한 문장을 얻습니다. 문장별 테스트: 삭제된 경우 독자가 잘못된 결정을 내릴까요, 아니면 단지 덜 안내받는다고 느낄까요? 잘못된 결정, 유지. 덜 안내받음, 삭제.
4. 명확성을 위해 훑기
동일한 텍스트에 대한 별도의 렌즈로, 세 가지를 찾습니다: 신입 독자가 해독할 수 없는 전문 용어, 한 숨에 풀기에는 너무 압축된 문장, 그리고 기술적으로 들리지만 아무것도 말하지 않는 표현("구성에 의해 유지됨", "설계상", "이를 활용하십시오"). 내부 전문 용어는 첫 사용 시, 같은 문장 안에서 인라인으로 정의하십시오. 분야를 일반적으로는 알지만 이 구석은 모르는 신입 사원에 맞추십시오. 가장 밀도가 높고 중요한 문단에 가장 많은 공간을 제공하십시오: 비트로 나누고, 아이디어당 하나의 문장, 원인을 결과보다 먼저. 테스트는 소리 내어 읽기입니다: 한 숨에 말할 수 없는 절, 또는 신입 사원이 멈춰 찾아볼 용어는 다시 써야 합니다.
명확성은 단순화가 아닙니다. 정확한 설명에 실제 데이터 모델이 필요한 경우 실제 데이터 모델을 사용하십시오. 죄는 독자로 하여금 풀어내게 하는 것이지, 세부 사항의 존재가 아닙니다. 내용이 진정한 병렬 참조 자료(열 목록, 부록, 오류 테이블)인 경우 밀도는 괜찮습니다. 그것들은 설계상 스캔 가능합니다. 산문화하지 마십시오.
5. 편집 메모 전달 후 대기
재작성 전에 보고하십시오. 메모는 다음 순서로 구성됩니다:
- 읽은 대로의 핵심. 문서가 전달한다고 이해한 내용을 명시하는 한두 문장. 이것은 아래 모든 것의 프레임이자 테스트입니다: 당신의 읽기가 작성자의 의도와 다르다면, 그 간격이 가장 큰 발견 사항입니다.
- 전체 진단. 지배적인 한두 가지 문제를 명확하게 명명하십시오. 깨진 아치를 50개의 라인 노트 아래에 묻지 마십시오.
- 발견 사항, 큰 것에서 작은 것으로. 반복되는 패턴의 경우, 패턴의 이름을 지정하고 두세 가지 대표적인 예를 제시하십시오. 모든 인스턴스를 철저히 나열하지 마십시오. 실제 텍스트를 인용하고, 작성자가 이동을 볼 수 있도록(규칙뿐만 아니라) 적어도 하나의 예에 대한 실제 대체 텍스트를 제안하십시오. 발견 사항을 이 스킬의 체크리스트가 아닌 작성자에게 중요한 것에 따라 구성하십시오. 위의 잡음 범주와 계층 이름은 문제를 찾기 위한 렌즈이며, 목차로서는 부적합합니다. 범주별 섹션이 있는 메모는 형식이 채워진 것으로 읽히는 반면, "독자에게 가장 큰 비용이 드는 것" 순서의 메모는 편집자처럼 읽힙니다.
- 계층. 다음으로 분할: 승인 시 적용할 수정 사항(기계적, 확인됨); 가시적으로 표시하지만 만들어 내지 않을 공백(누락된 섹션은
[TBD: ...]앵커가 되며, 내용을 발명하지 않음); 그리고 작성자에게 속한 판단 호출(완전성과 속도를 교환하는 삭제, 등록 선택). - 잘 작동하는 부분. 간략하게. 작성자는 수정 시 무엇을 건드리지 말아야 하는지 알아야 합니다.
메모 자체는 누군가가 읽는 문서이므로 자체 규칙을 따릅니다. 절차를 서술하지 말고("스킬에 따라 두 번 읽었습니다"), 문제가 없는 확인을 보고하지 말고("em-대시 발견되지 않음"), 살펴본 모든 것으로 채우지 마십시오. 발견 사항을 명시하십시오. 통과한 모든 것에 대한 보고는 침묵입니다.
그런 다음 멈추고 작성자가 응답하도록 하십시오. 승인하면 적용하십시오. 구조적 문제의 경우 문장을 제자리에 패치하는 것보다 문서를 처음부터 다시 쓰는 것을 선호하십시오. 프레이밍 결정은 문장 구조에 내장되어 있으며, 존재하지 말아야 할 문단을 다듬는 것으로는 고칠 수 없습니다. 차이 비교를 위해 이전 버전을 디스크에 남겨 두십시오.
6. 적용 후 확인
압축 및 재표현은 조용히 의미를 바꿀 수 있습니다. 재작성 후, 표현이 변경된 모든 주장을 해당 출처(코드, 데이터, 참조된 문서)와 다시 확인한 다음, 최종 문서를 낯선 사람으로서 처음부터 끝까지 한 번 더 읽으십시오. 중요도가 높은 문서의 경우, 가장 강력한 확인은 문서를 소리 내어 읽는 것입니다; 당신의 귀는 당신의 눈이 놓친 부자연스러운 부분을 잡을 것입니다.
중요한 참고 사항
- 이것은 기술 검토가 아닙니다. 정확성, 설계 또는 데이터 검증을 수행하지 마십시오. 프레젠테이션에 집중하십시오. 유일한 예외는 문서가 스스로 모순될 때입니다.
- 직접 재작성하지 마십시오. 먼저 편집 메모로 진단하십시오. 승인 시에만 적용하십시오.
- 메모 간결성 유지: 실제 발견 사항에 집중하고, 절차적 언어와 음성 확인을 피하십시오.
- 변경 사항 차이 비교: 특히 구조적 재작성의 경우 이해 관계자가 정확히 무엇이 변경되었는지 확인할 수 있도록 하십시오.
- 반복 소음 방지: 동일한 정보가 여러 섹션에 나타나면 종종 병합 충돌이나 불완전한 다시 쓰기를 나타냅니다. 병합하고, 어느 한 곳에 유지하고, 나머지에서 삭제하십시오.
- 누락된 내용을 발명하지 마십시오. 섹션이 완료되지 않았거나 스텁으로 남아 있는 경우, 내용을 채우는 대신
[TBD: ...]를 배치하십시오.
예시: 잡음 감소 시연
다음은 일반적인 에이전트 소음의 예시와 에디토리얼 패스가 어떻게 변환하는지 보여줍니다.
시나리오 A: 출처 서술
원본 (Before): As verified in the performance dashboard (confirmed with the SRE team in the daily standup), the tail latency for the payment endpoint increased by 35% after the last deploy.
편집 후 (After): Tail latency for the payment endpoint increased by 35% after the last deploy.
시나리오 B: 기각 가설 잔재
원본 (Before): We investigated whether the database migration caused the increased error rate. We confirmed it is not the cause. The migration completed successfully and rolled back cleanly. The actual cause was a misconfiguration in the load balancer.
편집 후 (After): The increased error rate was caused by a load balancer misconfiguration.
시나리오 C: 자기 참조적 발판
원본 (Before): [NEEDS VERIFICATION] The cron job runs hourly. (Verified: Yes, confirmed in the scheduler config.) The results are stored in S3.
편집 후 (After): The cron job runs hourly, with results stored in S3.
시나리오 D: 극화된 배경
원본 (Before): In a microservices architecture, services communicate with each other over the network. This is important because it allows for independent scaling and deployment. Our new service, the Inventory Service, which exemplifies this principle, manages stock levels.
편집 후 (After): The Inventory Service manages stock levels.