문서 편집

문서 편집은(는) 무엇을 하나요?

사실(fact)은 그대로 둡니다. 단어와 문장 구조를 다듬는 것입니다. 이 파일과 함께 있는 NOTES.md에 실제 예제가 있습니다.

기준

모든 문장은 독자에게 무엇을 해야 하는지, 무엇을 기대해야 하는지, 또는 잘못했을 때 어떤 일이 일어나는지를 말해야 합니다. 이 중 어느 것도 하지 않는 문장은 잘라냅니다. 간결함은 짧게 쓰는 것과 다릅니다: 분량을 맞추기 위해 내용을 자르지 말고, 내용을 감싸고 있는 부스러기를 자르십시오.

잘라낼 것

• 서론 늘리기. 첫 문장에 핵심을 넣으십시오.
• 같은 내용 반복. 가장 적절한 곳에서 한 번만 말하십시오.
• 군더더기 연결어 ("주목할 점은", "앞서 언급했듯이", "위하여").
• 행동을 바꾸지 않는 주관적 표현 ("화려하지는 않지만 중요한").
• 모호한 양 표현 ("놀라운 비율"). 실제로 효과가 있는 이유를 말하거나, 해당 주장을 잘라내십시오.
• 확정을 피하는 애매한 표현. 실제 불확실성을 의사 결정 기준과 함께 명확히 밝히십시오.
• 강조를 위한 인용 블록. 누군가의 행동을 바꾸는 경고에만 사용하십시오.

AI 생성 텍스트임을 드러내는 부분을 잘라낼 것

모델은 가장 다양한 독자에게 맞는 표현을 선택하고, 작가는 한 명의 독자와 하나의 주제에 맞춰 선택합니다. 먼저 문장 구조를 살피십시오. 단어 사용 습관은 모델마다 바뀌기 때문입니다. 문장은 이 독자에게 아직 없는 정보를 제공할 때만 남깁니다.

• 사실을 말하기 전에 준비 단계를 거치는 표현. 아무도 X라고 말하지 않았는데 "X가 아니라 Y"라고 말하기, 핵심을 반복하는 한 줄짜리 마무리, 핵심 앞에 서론 늘어놓기, 깊이 있어 보이지만 아무 주장도 하지 않는 속담. 사실을 말하십시오.
• 규칙적인 리듬. 삼항 구조와 대시를 남발하거나, 문장 시작을 반복하거나, 수식어를 쌓아올리는 경우. 세 항목이 있을 때만 세 항목을 사용하십시오.
• 과장. 평범한 사실을 중대하거나 강건하다고 표현하거나, 판매용 문구나 익명의 권위자를 인용하거나, 의미를 암시하는 "-하는" 형태의 수식어를 사용하는 경우. 실제 효과를 말하거나 잘라내십시오.
• 규칙적인 서식. 모든 항목을 굵게 표시하거나 모든 생각에 제목을 붙이는 경우. 강조나 구조가 아무 의미도 없습니다.
• 초안 잔재. 채팅 래퍼, 지식 한계 고지, 첫 문장으로 반복되는 제목, 주제가 아니라 문서 자체에 관한 텍스트.
• 잘못된 독자. 독자가 이미 아는 내용을 다시 설명해서 결정이 마지막에 등장하게 만드는 경우.

작성자가 의도한 내용을 보존하고, 잘라낸 부분을 대체하기 위해 무엇이든 새로 추가하지 마십시오. 실제 대조, 진정한 세 항목의 목록, 인용 출처는 그대로 둡니다. 내용에 아무것도 추가하지 않는 '정보 없는 표현'은 잘라냅니다.

보호: 이유는 결코 군더더기가 아닙니다

왜 (이 순서인지, 이 도구인지, 이 검사를 먼저 하는지, 이 단계를 건너뛸 수 없는지)를 설명하는 문장은 명령을 내리지 않더라도 그대로 둡니다. 그 이유는 독자가 문서가 예상하지 못한 상황을 처리하고 절차가 더 이상 적용되지 않는 때를 알 수 있게 해줍니다. 이유가 명확하지 않은 곳, 특히 의도가 규정이 없는 상황에서도 규정을 적용할 수 있게 해주는 보안 및 규정 준수 규칙에서는 어디든 이유를 제시하십시오. 문장이 장식과 이유를 함께 포함하고 있다면, 이유를 남기도록 다시 쓰십시오. 기준은 "이것 없이는 독자가 이 작업을 더 못하게 될까?" 입니다.

부당한 구조는 잘라낼 것

계층, 표, 행렬, 중첩 제목, 분기는 실제로 작업에 필요할 때만 추가하고, 엄격해 보인다고 추가하지 마십시오. 스스로에게 물어보십시오: 실제로 여기서 작업이 분기합니까? (모든 독자가 같은 경로를 따른다면 목록입니다). 이 단계가 필요합니까, 아니면 그냥 철저해 보이기 위한 것입니까? 절차가 네 단계라면 네 단계로 쓰십시오: 처음 읽을 때 따라할 수 있는 네 단계 절차가 스킵되는 정확한 아홉 단계 절차보다 낫습니다. 함정, 순서 관련 주의사항, 이유는 남깁니다.

모델이 로드하는 지시사항

규칙 시트, 스킬, 역할 파일, 프롬프트는 로드될 때마다 토큰 비용이 발생하며, 독자는 규칙의 이야기가 아니라 규칙 자체가 필요한 모델입니다. 로드 시점에 따라 비용을 책정하십시오 (D28):

• 매 세션마다 (규칙 시트, 스킬 및 역할 설명): 규칙만. 설명은 스킬이 다루는 내용과 로드 시점을 300자 미만으로 말합니다. tools/check.py가 예산을 적용합니다.
• 사용 시 (스킬 또는 역할 본문): 규칙과 이유 절 하나. 규칙이 선택 사항으로 읽힐 때에만 하나의 구체적인 실패 사례를 들고, 날짜, 개수, 프로젝트 이름은 포함하지 않습니다.
• 요청 시 (NOTES.md, EVIDENCE*.md): 사건, 숫자, 날짜, 출처. 본문은 그곳을 가리킵니다.

명령형으로 작성하십시오. 다른 로드된 파일이 이미 가지고 있는 규칙을 다시 말하지 말고, 그 이름으로 가리키십시오. docs/REQUIREMENTS.tsv에 고정된 요구사항은 해당 파일이 다시 작성될 때 함께 이동하며, 조용히 사라지지 않습니다.

절차의 형태

목적 → 사용 시점 → 시작하기 전에 → 단계 → 확인 → 작동하지 않을 경우 → 에스컬레이션

• 확인 단계는 절대 생략하지 마십시오: 가장 자주 건너뛰고 가장 가치 있는 부분입니다.
• 단계당 하나의 동작. UI 요소는 정확한 이름을 사용하십시오. 전체 경로를 제공하십시오.
• 되돌릴 수 없는 단계는 단계 전에 표시하십시오. 단계 후가 아닙니다.
• 유능하지만 환경을 모르는 사람을 위해 작성하십시오: 도메인은 알지만 이 환경을 본 적이 없는 사람.
• 제목은 누군가가 검색할 단어로 짓습니다. 날짜, 버전, "v2"는 포함하지 마십시오.

어조

• 평이한 언어, 짧은 문장.
• 제약 조건에 이가 있는 표현(몰수, 해지, 데이터 손실, 개인 책임)을 부드럽게 만들지 마십시오: 솔직하게 말하십시오.
• 공급업체 문서를 복사하지 말고 링크로 연결하고, 여러분의 작업 방식에 특화된 내용만 문서화하십시오: 전재는 오래된 정보가 됩니다.