jonshaw199/decision-doc-quality

의사 결정 / 옵션 문서 품질 가이드라인

엔지니어링 의사 결정, 스파이크, 또는 옵션 문서를 작성할 때는 다음 규칙을 따르세요. 독자는 컨텍스트가 전혀 없는 바쁜 팀원이며, 문서는 훑어보기 쉽고, 평이하며, 증명 가능해야 합니다.

독자: 컨텍스트 제로 가정

• 독자가 해당 도메인의 암묵적 지식을 전혀 모른다고 가정합니다. 모든 용어, 약어, 서비스 이름, 도구, 패턴(예: CDC, Debezium, Kafka, SNS, SQS, outbox, logical replication, Temporal)은 풀어서 설명하거나 하이퍼링크를 겁니다. "아무도 이것이 무엇을 의미하는지 모릅니다."
• 어떤 것이 무엇이고 무엇을 하는지를 평이한 말로 먼저 설명한 후에 그것에 의존하세요. 전문 용어만 단독으로 사용하는 것보다 평이한 문구 + 링크를 선호하세요.
• 요청받지 않는 한 별도의 용어집 섹션을 추가하지 말고, 대신 용어를 본문에 인라인으로 링크하세요.

작성 스타일

• 핵심을 먼저 말하세요(BLUF). 주요 내용을 먼저 제시하고, 그 다음에 세부 사항을 설명합니다.
• 짧게 작성하세요. 한 줄이 단락보다 낫습니다. 섹션이 텍스트 벽처럼 보이면 잘라내세요. 아무도 긴 문서를 읽지 않습니다.
• 평이한 언어를 사용하세요. AI 슬롭(AI-slop) 없음, "그럴듯하게 들리는" 채우기 없음, 문서 자체의 진화 과정에 대한 서술 없음, 문서 안에서 자신의 추론을 방어하지 않음(예: "직접적인 증거, 이론이 아님" 같은 표현 금지).
• 어디서든 em 대시(—)를 사용하지 마세요. 강조를 위해 모두 대문자(ALL-CAPS)를 사용하지 마세요(굵게 사용). 기계가 생성한 것처럼 보이는 장식용 번호 매기기나 가운뎃점 구분자를 사용하지 마세요.
• 팀이 수행할 작업에는 "우리(We)"를, 작성자의 의견/성향에는 "나(I)"를 사용하세요. 둘을 명확히 구분하세요.

구조

• 권장 사항 / TL;DR을 앞부분에 제시합니다. 몇 줄로 요약: 성향, 주요 이유(불릿 포인트), 팀 피드백 후 변경될 수 있는 살아있는 문서에 대한 초기 의견으로 제시합니다. 무관심과 유연성이 실제로 있을 때는 명시적으로 언급하되, 여전히 선호도와 그 이유를 제시합니다.
• 옵션당 하나의 접을 수 있는 블록(토글)을 사용합니다. 접힌 줄에는 짧은 레이블 + 한 줄의 평이한 영어 핵심을 표시합니다. 내부에는: 간단한 다이어그램, 작동 방식, 재사용되는 항목(증명 링크 포함), 순수 신규 항목, 규모/트레이드오프, 소규모 코드 또는 설정 스케치가 포함됩니다. 표면을 훑어보기 쉽게 유지하세요.
• 동료 섹션을 병렬로 유지하세요(일관성은 선택 사항이 아닙니다). 옵션/도구/후보는 형제 관계이므로 모든 항목이 동일한 템플릿을 따라야 합니다: 동일한 순서의 동일한 하위 섹션 제목, 동일한 다이어그램/미디어/코드 스케치의 존재, 동일한 깊이. (가장 강력한 섹션에서) 템플릿을 한 번 고정하고 모든 항목에 적용하세요. 섹션을 추가하거나 편집할 때 다른 섹션을 다시 정렬하세요. 각 섹션이 제각각의 형태로 표류하도록 두지 마세요. 구조가 다른 것은 엉성하게 보이며 쉬운 나란히 비교라는 전체 목적을 무너뜨립니다. 이것은 반복적인 실패 모드이므로 공유 전에 확인하세요.
• 하나의 명확한 축(예: 언제 발생하는지, 또는 어떻게 발생하는지)으로 옵션을 그룹화하세요. 하나의 그룹에 두 개의 축을 혼합하거나 겹치는 가짜 동료 카테고리를 만들지 마세요. 어떤 것이 다른 옵션(실행자, 배치 위치)의 구현 세부 사항이라면, 동료로 나열하지 말고 그 안에 포함시키세요.
• 공유/가장 어려운 핵심 부분을 자체 스케치로 설명하세요(전체 라이프사이클 처리, 예: 생성/업데이트 및 삭제).
• 다이어그램(Mermaid)을 사용하여 설명하세요. 정확하게 유지하세요(테이블을 별도의 DB로 그리지 않는 등).
• 피드백 초대로 끝내세요("다른 아이디어 있나요?"). 절대 갑자기 끝내지 마세요.
• 메타데이터는 최소한으로 유지하고, 필요한 것만 포함하세요(종종 티켓 링크만). 작성자가 신경 쓰지 않는 상태/상용구 줄은 삭제하세요.

옵션의 포괄성

• 일반적인 두세 가지가 아니라 모든 옵션을 빠짐없이 나열하세요. 실제 문제에는 많은 옵션이 있습니다. 명백히 나쁜 옵션도 포함시켜 전체 범위를 볼 수 있게 하세요(약함/기준선으로 레이블 지정).
• 항상 "아무것도 하지 않음" 기준선을 인정하고 그 결과를 명시하세요.
• 옵션과 올바른 용어를 찾기 위해 실제 출처(문서, Stack Overflow, Reddit, 벤더/패턴 참조)를 조사하세요. Wikipedia만으로는 게으른 기본값입니다. 관련 기본 출처를 찾으세요.
• 확립된 디자인 패턴 이름을 올바르게 지정하고 링크하세요. 패턴 이름을 잘못 적용하지 마세요. 인용하기 전에 패턴이 실제로 적합한지 확인하세요.

증거(핵심 규칙)

• 시스템에 이미 있는 것에 대한 모든 주장은 증명에 대한 하이퍼링크(소스 파일 + 라인, 인프라 구성, 티켓)로 뒷받침됩니다. 가정이나 추측은 없습니다.
• 주장을 링크로 증명할 수 없으면 사실로 명시하지 말고 검증되지 않음으로 표시하세요.
• 실제 파일/인프라를 직접 읽어 확인하세요. 하위 에이전트의 결과를 읽지 않고 사실로 단언하지 마세요. "내가 읽었다"와 "에이전트가 보고했다"를 구분하고, 중요한 경우 신뢰도를 명시하세요.
• 조용히 입장을 바꾸지 마세요. 검사 결과 이전 주장이 변경되면 무엇이 잘못되었고 그 이유를 말하고 수정하세요.
• 압박을 받으면 전제와 자신의 결론에 도전하고, 방어하는 대신 재검증하세요.
• 모든 식별자, 파일 이름, 티켓, PR 및 참조에 하이퍼링크를 걸고, 독자가 찾아다니도록 맨 식별자를 남겨두지 마세요.

옵션 문서 내용

• 어려운 공유 핵심(어느 옵션을 선택하든 필요한 작업)을 그 주변의 래퍼/메커니즘과 분리하고, 실제 노력과 위험이 무엇인지 명시하세요.
• 장단점을 근거를 들어 제시하세요. 과장하지 마세요("대부분의 작업과 거의 모든 위험" → 정확한 내용으로 완화).
• 각 옵션이 (이미 존재하는) 무엇을 재사용하고 무엇이 순수 신규인지 기록하세요.

프로세스

• 최소한의 목표 편집을 수행하세요. 작은 변경을 위해 전체 문서를 다시 작성하지 마세요.
• 민감한 표현의 경우 채팅에서 초안을 보여주고 적용하기 전에 반복적으로 수정하세요.
• 동봉하는 검토/Slack 메시지의 경우: 매우 짧고 진정으로 초대하는 방식으로 유지하세요(사람들은 바쁘고 읽고 싶어하지 않을 것입니다). 요청하지 않으면 긴급 또는 비긴급이라고 주장하지 마세요. 검토자에게 가장 유용한 단일 프레임을 제공하세요.

최종 확인

문서를 공유하기 전에 다음을 확인하세요:

• 주요 요점/권장 사항이 앞부분에 있고 짧은가?
• "우리가 가진 것"에 대한 모든 주장에 증명 링크가 있으며, 검증되지 않은 주장은 레이블이 지정되었는가?
• 전문 용어가 풀어서 설명되거나 링크되었으며, 컨텍스트가 없는 독자가 따라갈 수 있는가?
• 옵션이 하나의 명확한 축으로 그룹화되었으며, 각각 접을 수 있고 평이한 한 줄 요약이 있는가?
• em 대시, 모두 대문자 강조, 자기 서술, AI 슬롭이 없는가?
• "우리"와 "나"가 올바르게 사용되었으며, 성향은 명시되었지만 유연성은 명확한가?
• 문서가 피드백을 초대하며 갑자기 끝나지 않는가?