Skip to content

SKILL.ko.md

Latest commit

 

History

History
100 lines (77 loc) · 4.61 KB

SKILL.ko.md

File metadata and controls

100 lines (77 loc) · 4.61 KB

Skill: Structure First Docs (Korean Pair)

영문 기본 문서: SKILL.md

Purpose

문서를 위에서 아래로 한 번에 읽히게 작성/리뷰합니다. 핵심은 원문 보존입니다. 새 사실을 만들지 않고, 확정되지 않은 결정을 확정하지 않습니다. 유용한 원문 양식도 보존합니다. 이메일, 체크리스트, ADR, 인계 메모를 읽힘 개선 없이 한 가지 출력 형태로 평탄화하지 않습니다.

Modes

  1. Compose
  • 새 문서를 작성하거나 기존 문서를 재구성
  1. Review
  • 기존 문서를 검토하고 이슈/리스크를 먼저 반환

When to Use

  • 설계 문서, 리팩터/마이그레이션 계획, 런북, PR 설명 문서
  • 구현 전 기술 문서 리뷰

Do Not Use

  • 마케팅/브랜딩 카피
  • 정책/법무 전담이 필요한 엄격 컴플라이언스 문서

Core Rules

  1. 먼저 목적을 한 문장으로 고정한다.
  2. Primary Reader Flow는 원문 내용에서만 재배열해 만든다.
  3. 원문 보존 우선: 모든 문장은 원문에서 추적 가능해야 한다.
  4. 원문에 없는 사실/제약/수치/담당/일정/정책값을 새로 추가하지 않는다.
  5. 원문의 추정/가능성 표현을 확정 결정으로 승격하지 않는다.
  6. 추정 표현 강도를 유지한다. 일 수 있다, 같다, 그런 듯하다, 가능성이 높다, 아마도 같은 표현을 더 단정적으로 바꾸지 않는다.
  7. 시간 순서 자체가 의미인 문서(타임스탬프, 인계 순서, 사고 경과)는 그 chronology를 보존한다. 재배열이 읽힘을 높이더라도 의미 손실이 생기면 바꾸지 않는다.
  8. 정보가 비어 있으면 가정하지 말고 Open Questions 또는 Unknown으로 둔다.
  9. 원문 양식이 이미 유용하면 유지한다. 이메일은 이메일답게, 체크리스트는 체크리스트답게 둔다.
  10. 읽힘 개선 폭이 작으면 exact no-op를 우선한다. 구조를 보여주기 위해 억지로 손대지 않는다.
  11. 리뷰 출력은 항상 이슈/리스크부터 시작한다.
  12. 리뷰는 문서 상태/범위/리스크를 명확히 하는 데 집중한다. 원문이 이미 그 재설계를 다루지 않는다면 시스템 재설계로 번지지 않는다.

Compose Structure (Adaptive)

고정 템플릿을 강제하지 않는다. 원문 양식을 우선한다.

최소 섹션부터 시작:

  • Intent
  • Current Facts
  • Next Actions

필요할 때만 추가:

  • Decisions (원문에서 확정된 결정만)
  • Risks
  • Open Questions
  • Appendix

원문이 이미 충분히 읽히면:

  • exact no-op를 먼저 고려하고,
  • 원래 형식을 유지하거나,
  • 가벼운 재배열/라벨 정리만 한다.

Review Structure

  • Issues/Risks를 심각도 순으로 먼저 제시한다.
  • 그다음 Evidence, Required Changes를 제시한다.
  • Open Questions/Assumptions는 필요할 때만 둔다.
  • 요약은 요청된 경우에만 추가한다.
  • 새 설계를 제안하기보다, 문서의 상태/범위/라벨을 더 분명히 하도록 요구한다.

Execution Steps

  1. 모드(Compose/Review)를 먼저 확정한다.
  2. 원문 양식(이메일, 체크리스트, ADR, 인계 메모 등)을 먼저 식별한다.
  3. 원문에서 사실/결정/할 일/미확정 항목을 분리한다.
  4. 시간 순서 자체가 의미인지 먼저 확인한다.
  5. 필요한 만큼만 위에서 아래로 읽히게 재배열한다.
  6. 원문 양식이 이미 작동하면 유지하고, 필요할 때만 가변 섹션을 쓴다.
  7. 개선 폭이 작으면 exact no-op를 우선한다.
  8. 모든 문장이 원문 추적 가능한지 검증한다.
  9. 추정 표현 강도가 세지지 않았는지 검증한다.
  10. 미확정 정보는 질문으로 드러낸다.
  11. 출력은 구체적이고 비추측적으로 유지한다.
  12. 직접 수정 가능하면 대상 파일을 바로 수정한다.
  13. 직접 수정이 막히면 게시 가능한 Markdown과 실패 사유를 함께 반환한다.

Final Checks

  • 독자가 위에서 아래로 판단 흐름을 한 번에 따라갈 수 있는가?
  • 원문에 없는 새 사실이 추가되지 않았는가?
  • 미확정 아이디어가 확정 결정으로 바뀌지 않았는가?
  • 추정 표현 강도가 원문과 비슷하게 유지됐는가?
  • 시간 순서가 의미인 문서에서 chronology를 보존했는가?
  • 유용한 원문 양식을 괜히 평탄화하지 않았는가?
  • 문서에 과한 섹션이 붙지 않았는가?
  • exact no-op 또는 더 가벼운 수정이 더 나은 경우는 아니었는가?
  • 리뷰 모드에서 이슈/리스크가 최우선인가?
  • 리뷰가 시스템 재설계로 번지지 않았는가?