글쓰기 기준
개요: 아카이브 문서를 사람과 AI가 읽기 쉽게 쓰는 공통 기준입니다. 문서를 작성하거나 수정할 때만 확인합니다. 코드 구현 규칙은 coding-conventions.md에 둡니다.
독자
대화 맥락을 모르는 외부 독자도 이해할 수 있게 씁니다. 이 아카이브는 작성자만 보는 문서가 아닙니다.
문체
- 반말을 쓰지 않습니다.
한다,이다,해대신합니다,입니다를 씁니다. - 중점
·을 쓰지 않습니다. 쉼표(,)를 씁니다. - 문장을 끝내는 마침표(
.) 다음에는 다음 문장을 새 줄에 씁니다. 코드 블록, 표, 식별자는 예외입니다.
문체 규칙을 지킨 문장도 글 전체의 흐름이 어색할 수 있습니다. 퇴고에서 문장 사이 연결을 따로 확인합니다.
작성
핵심을 먼저 밝히고, 이유와 예시를 이어서 씁니다. 짧은 문장을 기계적으로 나열하지 않습니다. 문장을 잇는다는 이유로 불필요하게 길게 쓰지도 않습니다.
번역투, 모호한 표현, 같은 말의 반복 요약, 과도한 단정을 줄입니다.
개념을 정의할 때는 책임, 적용 범위, 경계를 적습니다. 일반적인 개념과 이 아카이브의 선택을 구분합니다. 이 저장소의 선택을 보편적인 정답처럼 쓰지 않습니다.
기술 용어는 필요한 만큼만 쓰고, 처음 나올 때 설명합니다.
표는 비교에 씁니다. 도식은 구조와 흐름에 씁니다.
문서 단위
에이전트가 넣거나 뺄 수 있게 Markdown 단위를 작게 둡니다.
필요할 때 가벼운 YAML frontmatter(id, title, description, tags, status)를 씁니다.
있는 문서만 링크합니다.
없는 큰 트리를 만들지 않습니다.
아직 확정되지 않은 개인 코딩 규칙은 아카이브에 올리지 않습니다.
그때는 TODO나 골격만 둡니다.
Docusaurus _category_.json은 탐색용입니다.
엔지니어링 의미를 정의하지 않습니다.
예시와 근거
설정이나 실행 방식이 핵심인 글에는 최소 적용 예시와 확인 방법을 둡니다. 모든 글에 코드를 넣지는 않습니다. 개념을 이해하고 적용하는 데 도움이 될 때 씁니다.
| 글의 목적 | 넣을 예시 |
|---|---|
| 선택 비교 | 같은 목적을 수행하는 코드 비교 |
| 설정 | 필요한 설정과 적용 범위 |
| 동작 | 입력부터 결과까지의 흐름 |
| 실행 모델 | 대기, 스레드, 자원 사용의 차이 |
| 예시 코드 | 가정, 생략한 부분, 실제 적용 시 주의점 |
사실, 작성자의 판단, 외부 참고 사례를 구분합니다. 출처보다 강한 주장을 만들지 않습니다. 확인되지 않은 성능 개선과 기업 전체의 전환 사례를 단정하지 않습니다.
ADR
아래는 안내입니다. 모든 ADR에 빈 절을 만들지 않습니다. 해당하지 않는 절은 생략합니다.
- 배경: 어떤 상황과 문제가 있었는지
- 검토한 대안: 무엇을 비교했는지
- 결정: 무엇을 선택했고 왜 선택했는지
- 적용 예시: 이해에 필요한 설정, 코드, 도식
- 결과와 제약: 얻는 점과 별도로 관리할 부분
- 관련 문서와 근거
참고 사례는 선택의 근거와 연결합니다. 링크만 나열하지 않습니다.
기존 결정 목록은 Decisions입니다.
퇴고
문서를 쓴 같은 에이전트가 확인합니다. 별도의 Reviewer나 글쓰기 에이전트를 실행하지 않습니다.
- 앞 문장이 다음 문장으로 자연스럽게 이어지는가
- 이유와 결론 사이에 설명이 빠지지 않았는가
- 대화에서만 통하는 표현이 남아 있지 않은가
- 같은 내용을 여러 절에서 반복하지 않는가
- 프로젝트의 선택을 보편적인 정답처럼 설명하지 않는가
- 코드, 설정, 설명이 서로 일치하는가
- 예시와 제약이 독자의 이해에 필요한 만큼 포함됐는가