gitifact 0.5.1 → 0.6.0

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

@@ -0,0 +1,54 @@
+# 문서 문체
+
+위키 페이지·요구사항·설계에 모두 적용한다. 본문은 '~한다', '~이다'로 통일하고 제목은 내용을 나타내는 명사형으로 쓴다. 화면 문구·인용·코드의 표현은 유지한다.
+
+## 서술과 구성
+
+- 대상과 규칙을 먼저 쓴다. '본 문서는 ~을 정의한다' 같은 서두보다 책임·의존 방향·처리 조건을 바로 설명한다.
+- 한 문단에는 한 주제를 담는다. 배경과 선택 이유는 해당 규칙을 이해하는 데 필요한 만큼만 쓴다.
+- 아키텍처 개요에는 시스템의 구성과 경계를 요약하고, 세부 규칙은 상세 문서로 연결한다. 다른 문서의 규칙을 복사하지 않는다.
+- 절차는 순서 목록, 비교와 조건별 처리는 표, 설명은 문단으로 쓴다. 짧은 내용에 소제목이나 표를 과하게 나누지 않는다.
+- 용어는 문서 전반에서 일관되게 사용한다. 익숙한 한국어로 설명할 수 있는 말에 영문을 반복해서 병기하지 않는다.
+
+## 구체성과 정확성
+
+- '유연성을 확보한다', '안정성을 강화한다'처럼 효과만 말하지 않는다. 무엇을 어떻게 처리하는지 쓴다.
+- 작업 지침에는 실행 위치·조건·명령·완료 기준을 적고, 실패나 미실행 시 처리 방법을 구분한다.
+- 현재 구현, 합의한 규칙, 미적용 전환안을 구분한다. 예정된 기능이나 실행하지 않은 검증을 완료된 사실로 쓰지 않는다.
+- 문장을 줄이더라도 적용 범위·예외·제약은 보존한다. 문체 교정으로 결정의 의미, ADR 상태·날짜, 식별자, 명령과 코드 예제를 바꾸지 않는다.
+
+## 인용과 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)을 사용할 수 있다.
+
+- `NOTE`: 놓치기 쉬운 보충 정보
+- `TIP`: 작업에 도움이 되는 선택적 요령
+- `IMPORTANT`: 작업 전에 알아야 할 필수 조건
+- `WARNING`: 문제를 피하려면 주의해야 할 사항
+- `CAUTION`: 데이터 손실 등 작업에 따르는 위험
+
+```markdown
+> [!IMPORTANT]
+> 통합 테스트를 실행하기 전에 Docker를 시작한다.
+```
+
+본문으로 충분히 전달되면 Alert를 쓰지 않는다. 문서당 1~2개 이내를 기본으로 하되 필요한 경우에만 추가한다. 연속 배치나 목록·인용구 안의 중첩은 피하고, 한 Alert는 한 주제를 한두 문장으로 설명한다. 긴 설명은 별도 절로 작성한다. 일반 인용구를 일괄 변환하지 않는다.
+
+같은 기준을 다이어그램에도 적용한다. 흐름이나 상태 전이가 글보다 그림으로 빨리 읽히는 자리에만 ` ```mermaid ` 펜스를 쓰고, 같은 내용을 글과 그림으로 두 번 적지 않는다. 설계 문서에도 필요하면 쓴다. 문서당 한두 개가 기준이다.
+
+## AI 슬롭 제거
+
+- 상투적인 도입·맺음말, 같은 내용을 반복하는 요약, 독자에게 말을 거는 문장을 삭제한다.
+- '중요한 것은', '반드시 기억해야 한다', '단순한 X가 아니라 Y다' 같은 강조·대조는 실제 구분이 필요할 때만 쓴다.
+- '체계적인', '효율적인', '강력한', '원활한'처럼 판단 기준이 없는 수식어는 삭제하거나 구체적인 동작으로 바꾼다.
+- 당연한 설명, 작성 과정의 중계, 요청을 수행했다는 보고를 본문에 섞지 않는다. 필요한 변경 이력은 이력 문서에서 관리한다.
+- 굵은 글씨·경고문을 반복하지 않는다. 놓치면 데이터 손실이나 잘못된 실행으로 이어지는 조건에만 경고를 둔다.
+- 편집 후 각 문장이 규칙·사실·이유·절차 중 무엇을 전달하는지 확인한다. 정보를 더하지 않는 문장은 삭제한다.
+
+| 피할 표현 | 작성 예 |
+| :--- | :--- |
+| 안정적인 병합을 위해 철저한 검증을 수행한다. | 필수 CI가 실패한 MR은 병합하지 않는다. |
+| 관심사를 명확히 분리하여 유지보수성을 높인다. | 화면은 입력·표시를, 서버는 권한·업무 규칙 검증을 담당한다. |
+| 중요한 것은 문서의 일관성을 유지하는 것이다. | 공통 규칙은 한 문서에서 관리하고 다른 문서는 링크로 참조한다. |
+
+요구사항의 사용자 스토리와 수용 조건에도 적용한다. 다만 `gitifact docs spec`이 정한 문형과 `조건: / 기대 동작:` 형식은 문체 교정의 대상이 아니다.