---
name: writing-documents-aim
description: Use when writing any document for external audience — Jira tickets, Confluence pages, IMS actions, GitLab MR descriptions, emails, or markdown reports
---

# Writing Documents

## Overview

모든 문서는 **독자 → 톤 → 구조 → 검토** 순서로 작성한다.

**Core principle:** 독자가 누구인지 먼저 결정하고, 독자의 수준에 맞게 추상화한다. 코드 분석 결과를 그대로 옮기는 것은 문서가 아니다.

**두괄식 필수:** 모든 문단/섹션은 결론부터 쓴다. 배경→분석→결론 순서 금지. 결론→근거→상세 순서로 작성한다. 두괄식이 아닌 문단은 삭제하고 재작성한다.

**그림 우선 (다이어그램 + 데이터 차트):** 글로 설명하기 전에 그림으로 표현할 수 있는지 먼저 검토한다. 그림은 두 종류로 나누며, 둘 다 PNG로 렌더해 문서에 첨부한다.

- **정성(관계·흐름·구조)** → mermaid (flowchart, sequence, ERD 등)
- **정량(분포·시계열·비교·상관)** → matplotlib (히스토그램, box plot, bar, 시계열 등)

mermaid는 데이터 분포/시계열/box plot을 그리지 못하므로(xychart 한계), 정량 데이터를 mermaid로 억지로 그리거나 표만 넣고 끝내지 않는다. ASCII art·ASCII 차트 금지 — 렌더링 가능한 도구를 사용한다. 상세는 `markdown-guide.md` / `confluence-guide.md` 참조.

<HARD-GATE>
문서를 발송/게시/등록하기 전에 반드시 사용자에게 초안을 보여주고 승인을 받는다. 승인 없이 send, post, publish, submit 하지 않는다.
</HARD-GATE>

**동사 분리 (HARD-GATE보다 강력):**

"작성"과 "저장"은 **완전히 다른 동작**이다. 절대 합쳐서 수행하지 않는다.

| 사용자 동사 | 의미 | 허용 동작 |
|-----------|------|----------|
| "작성해", "써줘", "입력해" | 에디터에 입력만 | 내용 입력 후 **반드시 멈추고** 사용자에게 보여준다. 저장 함수 호출 금지. |
| "저장해", "save", "submit" | 저장 실행 | 저장 함수(fileUpload, doRndSave 등) 호출 허용 |
| "등록해", "보내줘", "발송해" | 게시/발송 실행 | API 호출 허용 |

**턴 분리:** 저장 함수(fileUpload, doRndSave, API POST 등)는 **내용 입력과 같은 턴에서 호출 금지**. 반드시 사용자 메시지를 거친 후에만 호출한다.

```
Turn 1: 에디터에 내용 입력 → "입력 완료. 확인해 주십시오." (여기서 멈춤)
Turn 2: 사용자: "저장해" / "save" / "submit"
Turn 3: 저장 함수 호출
```

## When to Use

- Jira 작성 (description, 댓글, 상태/핸들러 변경)
- Confluence 작성 (페이지, 댓글)
- IMS 작성 (액션, 패치 검증서)
- GitLab 작성 (MR description, MR 코멘트)
- 메일 작성
- markdown 작성 (plan, report, 분석 문서 등)
- 매뉴얼 작성 (AIM 제품 매뉴얼, Antora/AsciiDoc, `openFrame_aim` 저장소 `7.3_main`) — `manual-guide.md`

## 4-Step Process

```
1. 독자 식별 → 2. 톤/추상화 수준 결정 → 3. 플랫폼 가이드 따라 작성 → 4. 사용자 검토
```

### Step 1: 독자 식별

| 독자 | 추상화 수준 | 예시 |
|------|-----------|------|
| **QA** | 동작 관점. 상수명/함수명/코드 레벨 설명 금지 | "세션 종료 기능 추가" |
| **개발자 (같은 팀)** | 모듈/함수 수준. 코드 블록 허용, 맥락 설명 포함 | "assign.c의 ACS skip 로직 제거" |
| **개발자 (다른 팀)** | 모듈 수준. 내부 구현 최소화, 인터페이스 중심 | "ACS 프로시저의 ASSIGN 해석 지원" |
| **PM/고객** | 기능/비즈니스 관점. 기술 용어 최소화 | "ACS 환경에서 PF키 기능 매핑 지원" |

**판단 기준:** 독자가 모르는 용어를 사용하면 안 된다. 확신이 없으면 한 단계 높은 추상화를 선택한다.

### Step 2: 톤

- **기본: 격식체** ("~합니다", "~드립니다")
- 모든 플랫폼에서 격식체를 기본으로 사용
- **인사: "안녕하십니까"로 통일** (모든 문서/메일/IMS/Jira 댓글)
- markdown (내부 문서): 격식체 또는 간결체 허용

### Step 3: 플랫폼별 가이드

각 플랫폼의 상세 규칙은 별도 가이드 파일 참조. **SKILL.md에는 abbreviated summary만** 있음. 구체 형식/적신호 체크리스트는 각 guide에서만 제공.

| 플랫폼 | 가이드 파일 | Read 의무 | 호출 스킬 | 핵심 규칙 |
|--------|-----------|:---:|---------|----------|
| Jira | `jira-guide.md` | ✅ | issue-analysis-aim 등 | description/댓글/상태변경 템플릿 |
| Confluence | `confluence-guide.md` | ✅ | — | 페이지 구조, 분량 조절, 독자 프레이밍 |
| IMS | `ims-guide.md` | ✅ | completing-patch-aim 등 | 액션/패치 검증서, X-Free Editor HTML |
| GitLab | `gitlab-guide.md` | ✅ | finishing-a-development-branch-aim | MR description (default.md), 코멘트 |
| Mail | `mail-guide.md` | ✅ | — | 제목/본문/서명, 발신자 규칙 |
| Markdown | `markdown-guide.md` | ✅ | — | plan/report/분석 문서 |
| Manual | `manual-guide.md` | ✅ | finishing-a-development-branch-aim (marker), completing-patch-aim | AIM 제품 매뉴얼 (Antora/AsciiDoc, 경험적 검증, 8단계 워크플로우) |

**"상세는 <guide> 참조" 링크를 만나면 반드시 해당 guide를 Read 후 작성한다**. summary로 대체 금지.

### Step 4: 사용자 검토

1. 초안을 텍스트로 사용자에게 보여준다
2. 사용자가 승인하면 발송/게시한다
3. 사용자가 수정을 요청하면 반영 후 다시 보여준다

**절대 금지:**
- 초안 없이 바로 발송/게시
- "확인해 주세요"라고 하면서 이미 발송한 상태
- 발신자 정보를 임의로 설정

## Quick Reference

| 체크 | 항목 |
|:---:|------|
| [ ] | 독자가 누구인지 식별했는가? |
| [ ] | 독자가 모르는 용어를 사용하지 않았는가? |
| [ ] | 격식체를 사용했는가? |
| [ ] | 플랫폼 가이드의 템플릿을 따랐는가? |
| [ ] | 사용자에게 초안을 보여주고 승인을 받았는가? |

## Common Rationalizations

| 에이전트의 변명 | 현실 |
|--------------|------|
| "send라고 했으니까 바로 보내야지" | HARD-GATE: 초안 → 사용자 승인 → 발송. send 지시는 초안 작성 지시다 |
| "발신자 정보가 없으니 만들면 되지" | 임의 생성 금지. 사용자 정보만 사용 |
| "상세할수록 좋지" | 문서 목적에 맞는 분량. 공유 페이지에 설계 문서 수준은 과도 |
| "코드 금지라고 했으니까 전부 제거" | 독자가 개발자면 핵심 코드는 허용. 독자별 추상화 표 참조 |
| "합리적인 구조를 만들면 되지" | 프로젝트 템플릿이 있으면 그것을 따른다. 임의 구조 생성 금지 |
| "다이어그램은 텍스트로 그려도 되지" | ASCII art 금지. mermaid 등 렌더링 도구 필수 |
| "데이터 분포도 mermaid로 그리면 되지" | mermaid는 정량 데이터를 못 그린다. 분포·시계열·비교는 matplotlib PNG. 표만으로 대체 금지 |
| "안녕하세요도 격식체 아닌가" | "안녕하십니까"로 통일. 다른 표현 금지 |
| "간단한 문서라 두괄식 안 해도 되지" | 모든 문서에 두괄식. 예외 없음 |
| "다이어그램 그리기 어려우니 텍스트로" | 어려워도 그린다. 글보다 그림이 우선 |
| "빨리 해달라고 했으니 검토 생략" | 압박은 승인 게이트를 건너뛸 이유가 안 됨 |
| "한 줄이니까 인사/구조 생략해도 되지" | 짧아도 가이드를 따른다. IMS 댓글도 인사 포함, 메일도 구조 유지 |
| "사용자가 한 줄만 하라고 했으니 두괄식/다이어그램 불필요" | 사용자 지시가 가이드와 충돌하면 가이드를 따르되, 사용자에게 알린다 |
| **"작성해줘 = 등록해도 된다는 뜻"** | **"작성"은 입력만. "저장/save/submit"이 아니면 저장 함수 호출 금지. 동사 분리 표 참조** |

## Common Mistakes

### 분석 보고서를 그대로 복사

- **Problem:** analysis_report.md의 코드 추적 결과를 Jira/메일에 그대로 옮김
- **Fix:** 독자 수준에 맞게 추상화. 독자별 추상화 표 참조

### 과잉 교정

- **Problem:** "코드 금지"를 듣고 개발자 대상 문서에서도 코드를 전부 제거
- **Fix:** 독자가 개발자면 핵심 코드 허용. 규칙은 독자별로 다름

### 미괄식 작성

- **Problem:** 배경 → 분석 → 결론 순서로 작성
- **Fix:** 결론 → 근거 → 상세. 두괄식이 아니면 해당 문단 삭제 후 재작성

### 승인 없이 발송

- **Problem:** 메일을 작성하자마자 바로 send
- **Fix:** 반드시 초안 → 사용자 검토 → 승인 → 발송

## Red Flags

- 독자를 식별하지 않고 작성 시작
- **두괄식이 아닌 문단** — 배경부터 시작하는 문단은 삭제하고 결론부터 재작성
- **다이어그램 없이 긴 텍스트로 흐름/구조 설명** — mermaid로 먼저 그린다
- **ASCII art로 다이어그램** — mermaid 등 렌더링 도구 사용
- **정량 데이터(분포/시계열/비교)를 mermaid로 그리거나 표만으로 끝냄** — matplotlib PNG로 렌더해 첨부
- 코드 블록이 QA/PM 대상 문서에 포함
- 격식체가 아닌 반말/간결체 사용 (내부 md 제외)
- 인사가 "안녕하십니까"가 아닌 다른 표현
- 사용자 승인 없이 발송/게시/등록
- "이미 보냈습니다" — 되돌릴 수 없는 상황
- **"작성해줘"를 듣고 저장까지 수행** — "작성"은 입력만, 저장은 별도 동사 필요
- **입력과 저장을 같은 턴에서 수행** — 반드시 사용자 메시지를 거친 후 저장
- 발신자/수신자를 임의로 설정

## Integration

**Called by:**
- **issue-analysis-aim** — IMS 답변 초안, Jira feature request 작성 시
- **completing-patch-aim** — 패치 검증서 공통 규칙(독자/톤/두괄식) + Step 0 marker 기반 `manual-guide` 자동 호출 (marker 없으면 Step 1, `pending-merge`면 Step 2~8)
- **finishing-a-development-branch-aim** — MR description 작성 시(`gitlab-guide.md`) + Step 5 Option 1/2 직후 `manual-guide` Step 1 자동 호출 (필요성 판단 + MR description에 marker 삽입)
- **code-reviewer-aim** Phase F — MR 코멘트 작성 시(`gitlab-guide.md`)

**Auto-trigger (manual-guide 전용)**:
`finishing-branch` + `completing-patch`가 MR 생명주기에서 `manual-guide`를 자동 호출한다. 상태 공유는 MR description의 HTML 주석 marker(`<!-- aim-harness:manual-check ims=... status=... -->`)로 하며, IMS 단위로 기록. 복수 IMS MR은 각 IMS별 marker. 상세는 `manual-guide.md`의 "Marker 형식" 섹션과 `manual-guide.md` Integration 섹션 참조.

**Pattern:** 이 스킬은 문서 작성의 hub로, 다른 스킬에서 cross-reference되어 사용된다. 직접 호출도 가능. 7개 서브가이드(jira/confluence/ims/gitlab/mail/markdown/**manual**)를 동봉.