explain-for-no-context

Files (1)

• SKILL.md

SKILL.md (first lines)

# explain-for-no-context

독자의 기술 수준을 낮춰 잡기보다, 거시적인 배경과 흐름부터 차근차근 설명한다. 설명을 듣고 나서 '무슨 일이고, 왜 생겼고, 지금 어디까지 왔는지'를 이해할 수 수 있어야 한다.

## 설명하기 전

- 과거 대화의 내용이 필요하면 확인 가능한 기록을 찾는다.
- 내부적으로 사건의 출발점, 해결하려는 문제, 관련된 사람이나 시스템의 역할, 핵심 동작, 현재 상태를 파악한다. 이것은 **작성용 메모**이지 출력 목차가 아니다.

## 설명할 때

- 일이 시작된 이유에서 출발해, 실제로 무엇이 일어나는지, 그래서 지금 무엇이 달라졌거나 막혀 있는지를 자연스러운 문단으로 잇는다. 원인과 결과를 먼저 알려주고, 파일명·함수명·약어는 이해에 필요할 때 최소한으로 끼워 넣는다.

- 일반 기술 개념을 다시 강의하지 말고, 그 개념이 **이 사례에서** 어떤 일을 하는지 설명한다. 도메인 용어집이 있다면 최대한 활용한다. 생소한 개념이면 짧게 풀어 쓴다.

- 분량은 이해에 필요한 만큼만 쓴다. 간단한 질문은 몇 문장으로, 복잡한 주제는 짧은 문단 몇 개로 풀어 쓴다. 독자가 이어서 파고들 세부사항은 필요할 때만 덧붙인다.

## 형식은 내용에 맡긴다

- 필요한 경우 같은 설명을 쉬운 말로 두 번 반복한다.
- 표는 여러 항목을 실제로 비교해야 이해가 빨라질 때만 쓴다. 상태나 역할이 둘 이상이라는 이유만으로 표를 넣지 않는다.
- 제목과 목록은 긴 설명에서 독자가 길을 잃지 않게 할 때만 쓴다. 마지막에 억지로 다음 행동을 붙이지 않는다. 사용자가 작업에 복귀하려는 경우에만 지금 볼 만한 구체적인 지점을 알려준다.
- 상대를 어린아이처럼 대하지 않는다. 능숙하지만, 차근차근 이해가 필요한 이 일에 낯선 사람으로 대한다.

## 응답 점검

첫 두 문장만 읽고도 무엇과 왜를 알 수 있는가? 이 대화를 처음 접하는 사람이 고유명사의 역할과 사건의 인과관계를 따라갈 수 있는가? 확실하지 않은 사실을 꾸며 넣지 않았는가? 불필요한 표와 제목을 빼도 설명이 더 잘 읽히는가?

From Jonghakseo/my-pi, MIT.

More from Jonghakseo/my-pi