gitifact 0.7.0 → 0.8.0

package/dist/i18n/ko/docs/writing.md

@@ -1,13 +1,16 @@
-# 문서 문체
+---
+title: 문서 문체
+description: 지침·요구사항·설계·결정기록에 공통으로 적용하는 문체, 본문과 결정기록의 구분, 인용·Alert·다이어그램, AI 슬롭 제거
+---
 
-위키 페이지·요구사항·설계에 모두 적용한다. 문서는 CLI 표시 언어와 무관하게 프로젝트의 언어로 쓴다. 본문은 '~한다', '~이다'로 통일하고 제목은 내용을 나타내는 명사형으로 쓴다. 화면 문구·인용·코드의 표현은 유지한다.
+프로젝트 지침·요구사항·설계에 모두 적용한다. 문서는 CLI 표시 언어와 무관하게 프로젝트의 언어로 쓴다. 본문은 '~한다', '~이다'로 통일하고 제목은 내용을 나타내는 명사형으로 쓴다. 화면 문구·인용·코드의 표현은 유지한다.
 
 ## 서술과 구성
 
 - 대상과 규칙을 먼저 쓴다. '본 문서는 ~을 정의한다' 같은 서두보다 책임·의존 방향·처리 조건을 바로 설명한다.
-- 한 문단에는 한 주제를 담는다. 배경과 선택 이유는 해당 규칙을 이해하는 데 필요한 만큼만 쓴다.
+- 한 문단에는 한 주제를 담고 첫 문장에 요지를 쓴다. 문단은 3~4문장, 300자 안팎이 기준이다. 넘으면 주제가 둘인지 보고 나누거나 표로 옮긴다.
 - 아키텍처 개요에는 시스템의 구성과 경계를 요약하고, 세부 규칙은 상세 문서로 연결한다. 다른 문서의 규칙을 복사하지 않는다.
-- 절차는 순서 목록, 비교와 조건별 처리는 표, 설명은 문단으로 쓴다. 짧은 내용에 소제목이나 표를 과하게 나누지 않는다.
+- 절차는 순서 목록, 비교와 조건·경우별 처리는 표, 흐름·상태 전이·구성 요소 관계는 다이어그램, 설명은 문단으로 쓴다. 짧은 내용에 소제목이나 표를 과하게 나누지 않는다.
 - 용어는 문서 전반에서 일관되게 사용한다. 익숙한 한국어로 설명할 수 있는 말에 영문을 반복해서 병기하지 않는다.
 
 ## 구체성과 정확성
@@ -17,32 +20,60 @@
 - 현재 구현, 합의한 규칙, 미적용 전환안을 구분한다. 예정된 기능이나 실행하지 않은 검증을 완료된 사실로 쓰지 않는다.
 - 문장을 줄이더라도 적용 범위·예외·제약은 보존한다. 문체 교정으로 결정의 의미, ADR 상태·날짜, 식별자, 명령과 코드 예제를 바꾸지 않는다.
 
+## 지금의 내용과 경위
+
+본문에는 지금 유효한 동작과 규칙만 쓴다. '전에는 …했는데 …라서 바꿨다', 바꾼 날짜와 계기, 옛 방식, 측정해 가며 고른 과정은 본문에 두지 않고 결정기록에 쓴다(`gitifact guide show records`). 읽는 사람은 이유를 `gitifact records list --doc <ID>`로, 옛 원문을 `gitifact specs show <ID> --ref <커밋>`으로 본다.
+
+문서를 고칠 때는 바뀐 문장을 고쳐 쓰고 옛 동작을 설명하는 문장을 덧붙이지 않는다. 지켜야 할 결정은 본문에 규칙으로 쓰고, 그 맥락과 검토한 대안은 결정기록에 둔다. 설계나 지침에 결정 표를 따로 두지 않는다.
+
 ## 인용과 Alert
 
-일반 인용구는 다른 문서나 발언을 인용할 때 쓴다. 보충 설명·필수 조건·주의사항을 따로 강조할 필요가 있으면 기본 인용구 대신 [GitHub Alert 문법](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)을 사용할 수 있다.
+일반 인용구는 다른 문서나 발언을 인용할 때 쓴다. 문장 속에 묻히면 다음 작업자가 놓치기 쉬운 내용은 [GitHub Alert 문법](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)으로 따로 둔다.
 
-- `NOTE`: 놓치기 쉬운 보충 정보
-- `TIP`: 작업에 도움이 되는 선택적 요령
-- `IMPORTANT`: 작업 전에 알아야 할 필수 조건
-- `WARNING`: 문제를 피하려면 주의해야 할 사항
-- `CAUTION`: 데이터 손실 등 작업에 따르는 위험
+| 종류 | 쓰는 자리 | 설계·지침의 예 |
+| :--- | :--- | :--- |
+| `IMPORTANT` | 깨면 안 되는 불변 조건, 작업 전에 알아야 할 필수 조건 | 원본 파일을 바꾸지 않는다, 실패를 조용히 삼키지 않는다 |
+| `WARNING` | 어기면 보안 문제나 잘못된 동작으로 이어지는 조건 | 인증 없이 열린 경로의 범위를 넓히지 않는다 |
+| `CAUTION` | 데이터 손실처럼 되돌리기 어려운 위험 | 이 명령은 기록을 지운다 |
+| `NOTE` | 알려진 한계, 예정된 제거, 놓치기 쉬운 보충 정보 | 이 경우는 구분하지 못한다, 이 코드는 다음 주요 버전에서 지운다 |
+| `TIP` | 작업에 도움이 되는 선택적 요령 | 확인할 때 쓰는 명령 |
 
 ```markdown
 > [!IMPORTANT]
 > 통합 테스트를 실행하기 전에 Docker를 시작한다.
 ```
 
-본문으로 충분히 전달되면 Alert를 쓰지 않는다. 문서당 1~2개 이내를 기본으로 하되 필요한 경우에만 추가한다. 연속 배치나 목록·인용구 안의 중첩은 피하고, 한 Alert는 한 주제를 한두 문장으로 설명한다. 긴 설명은 별도 절로 작성한다. 일반 인용구를 일괄 변환하지 않는다.
+본문으로 충분히 전달되면 Alert를 쓰지 않는다. 파일당 한두 개가 기준이며 필요한 경우에만 더한다. 연속 배치나 목록·인용구 안의 중첩은 피하고, 한 Alert는 한 주제를 한두 문장으로 설명한다. 긴 설명은 별도 절로 작성한다. 일반 인용구를 일괄 변환하지 않는다.
+
+## 다이어그램
+
+흐름, 주고받기, 상태, 관계처럼 글보다 그림으로 빨리 읽히는 자리에 ` ```mermaid ` 펜스로 넣는다. 먼저 내용에 맞는 종류를 고른다.
+
+| 내용 | 종류 |
+| :--- | :--- |
+| 갈라지거나 합쳐지는 처리 흐름, 판단 | `flowchart` |
+| 여러 구성 요소가 차례로 주고받는 요청·응답 | `sequenceDiagram` |
+| 대상이 거치는 상태와 전이 조건 | `stateDiagram-v2` |
+| 저장 구조의 표·엔터티 관계 | `erDiagram` |
+| 브랜치·병합처럼 커밋 이력의 모양 | `gitGraph` |
+| 모듈·타입의 의존과 구성 | `classDiagram` 또는 `flowchart`의 묶음 |
+
+그림이 맞지 않는 내용도 있다. 한 줄로 이어지는 순서는 번호 목록, 조건과 결과의 대응은 표가 낫다.
 
-같은 기준을 다이어그램에도 적용한다. 흐름이나 상태 전이가 글보다 그림으로 빨리 읽히는 자리에만 ` ```mermaid ` 펜스를 쓰고, 같은 내용을 글과 그림으로 두 번 적지 않는다. 설계 문서에도 필요하면 쓴다. 문서당 한두 개가 기준이다.
+- 상자 이름은 짧은 명사로 쓴다. 명령·경로·설정값 같은 세부는 그림 아래 표나 글에 둔다.
+- 상자는 10개 이하, 가로로 늘어서는 상자는 5개 이하가 기준이다. 더 길면 위에서 아래(`TD`)로 그리거나 그림을 나눈다.
+- 주 흐름을 먼저 선언하고 곁가지를 나중에 선언한다. 마름모는 판단에만 쓰고 그 라벨은 몇 글자로 줄인다.
+- 같은 출처나 모듈은 `subgraph`로 묶는다. 간선 라벨은 조건일 때만 두세 단어로 쓴다.
+- 색·`classDef`·`style`은 쓰지 않는다. 화면 모드와 색 조합은 보는 쪽이 정한다.
+- 그림으로 보인 내용을 글로 다시 풀지 않는다. 글에는 그림에 없는 조건과 예외만 적는다.
 
 ## AI 슬롭 제거
 
 - 상투적인 도입·맺음말, 같은 내용을 반복하는 요약, 독자에게 말을 거는 문장을 삭제한다.
 - '중요한 것은', '반드시 기억해야 한다', '단순한 X가 아니라 Y다' 같은 강조·대조는 실제 구분이 필요할 때만 쓴다.
 - '체계적인', '효율적인', '강력한', '원활한'처럼 판단 기준이 없는 수식어는 삭제하거나 구체적인 동작으로 바꾼다.
-- 당연한 설명, 작성 과정의 중계, 요청을 수행했다는 보고를 본문에 섞지 않는다. 필요한 변경 이력은 이력 문서에서 관리한다.
-- 굵은 글씨·경고문을 반복하지 않는다. 놓치면 데이터 손실이나 잘못된 실행으로 이어지는 조건에만 경고를 둔다.
+- 당연한 설명, 작성 과정의 중계, 요청을 수행했다는 보고를 본문에 섞지 않는다. 바뀐 경위는 커밋의 변경 이유에 쓴다.
+- 굵은 글씨·경고문을 반복하지 않는다. 강조는 "인용과 Alert"의 기준에 맞는 자리에만 둔다.
 - 편집 후 각 문장이 규칙·사실·이유·절차 중 무엇을 전달하는지 확인한다. 정보를 더하지 않는 문장은 삭제한다.
 
 | 피할 표현 | 작성 예 |
@@ -51,4 +82,4 @@
 | 관심사를 명확히 분리하여 유지보수성을 높인다. | 화면은 입력·표시를, 서버는 권한·업무 규칙 검증을 담당한다. |
 | 중요한 것은 문서의 일관성을 유지하는 것이다. | 공통 규칙은 한 문서에서 관리하고 다른 문서는 링크로 참조한다. |
 
-요구사항의 사용자 스토리와 수용 조건에도 적용한다. 다만 `gitifact docs spec`이 정한 문형과 `조건: / 기대 동작:` 형식은 문체 교정의 대상이 아니다.
+요구사항의 사용자 스토리와 수용 조건에도 적용한다. 다만 `gitifact guide show spec`이 정한 문형과 `조건: / 기대 동작:` 형식은 문체 교정의 대상이 아니다.