---
name: writing-as-the-person-who-did-it
description: Use when a Korean technical document is accurate, well-ordered and well-evidenced but reads like a report produced by nobody — no one chose anything, nothing surprised anyone, and the limits are an inventory instead of an admission.
metadata:
  version: "1.0.0"
  language: "ko-KR"
---

# 일한 사람이 쓴 글로 만들기

## 무엇을 고치는 스킬인가

문장도 맞고 순서도 맞고 근거도 붙어 있는데 **아무도 쓰지 않은 글처럼 읽히는** 상태를 고친다.
증상은 셋이다.

- 무엇을 골랐다는 말은 있는데 **왜 그것을 골랐는지, 무엇과 견주었는지**가 없다
- 확인하지 못한 것이 **목록**으로 있고, 그것이 걸리는 대목에는 없다
- 어긋난 자리가 없다. 처음부터 지금 구조를 알고 있었던 것처럼 읽힌다

고치는 방법은 하나뿐이다. **자료에 남아 있는 사람의 흔적을 찾아서 제자리에 놓는다.**

## 절대 규칙 — 없는 사람을 만들지 않는다

이 스킬을 잘못 쓰면 지어낸 경험이 붙는다. 그것이 아무 목소리도 없는 글보다 나쁘다.

**쓸 수 있는 것은 자료가 기록한 사람의 행동과 판단뿐이다.** 넣은 문장마다 그것이 어느 파일,
어느 칸, 어느 줄에서 왔는지 댈 수 있어야 한다. 못 대면 지어낸 것이다.

| 이런 말이 떠오르면 | 실제로 벌어지는 일 |
|---|---|
| 「처음에는 X를 의심했다」 | 자료에 그런 기록이 없으면 없던 수사 과정을 만든 것이다 |
| 「놀랍게도」·「당황스럽게도」 | 감정을 지어냈다. 관측이 뜻밖이었다는 근거가 자료에 없다 |
| 「고민 끝에 Y를 골랐다」 | 대안을 견주었다는 기록이 없으면 고민도 없었다 |
| 「많은 시행착오를 겪었다」 | 시행착오가 자료에 있으면 그것을 적고, 없으면 이 문장도 없다 |
| 「이 글이 도움이 되길 바란다」 | 기록에는 독자에게 인사하는 자리가 없다. 참고 글의 습관을 옮겨 온 것이다 |
| 「~로 읽기 쉽다. 그렇지 않다」 | 자료에 그런 오독 기록이 없으면 독자를 지어낸 것이다. 관측부터 적는다 |

`../rewriting-technical-prose-naturally/references/protected-content.md`가 함께 걸린다. 수치·버전·
식별자는 이 스킬에서도 한 글자도 바뀌지 않는다.

## 자료 어디에 사람이 남아 있나

기록을 열기 전에 이것부터 찾는다. 대개 **이미 문서 안에 있고 자리가 틀렸을 뿐**이다.

| 어디 | 무엇이 있나 |
|---|---|
| `확인하지 못한 것` 칸 | 재지 않은 것을 아는 사람이 적어 둔 것이다. 목록이 아니라 그 대목에서 할 말이다 |
| `재현 조건` 칸 | 누군가 실제로 이 순서로 돌렸다. 그 순서가 왜 그 순서인지가 대개 빠져 있다 |
| javadoc·README·주석 | 코드를 쓴 사람이 남긴 말. 그대로 옮길 수 있다 |
| 커밋 메시지 | 왜 지웠는지·왜 바꿨는지가 한 줄로 남아 있다 |
| `final/document.md` | 기록으로 뽑으면서 잘라낸 판단이 여기 남아 있는 경우가 많다 |
| 결정 기록의 `판단 이유`·`영향` | 감수한 비용이 적혀 있다 |

찾은 것이 없으면 **이 스킬은 여기서 끝난다.** 없는 목소리를 채우지 않는다.

## 옮길 수 있는 다섯 가지

참고 여섯 편에서 뽑았고, 각 항목이 어느 글에서 왔는지는
[references/voice-moves.md](references/voice-moves.md)에 있다. 여섯 편이 다 쓰는 것이 아니다 —
13569 한 편에 몰려 있고 23625는 거의 쓰지 않는다. **글마다 자료가 허락하는 만큼만 쓴다.**

1. **고른 이유를 견준 대상과 함께 적는다** — 무엇을 놓고 무엇을 골랐고 무엇을 감수했나
2. **확인하지 못한 것을 그 대목에서 말한다** — 끝의 목록이 아니라 그 주장 옆에서
3. **어긋난 자리를 남긴다** — 예상과 결과가 달랐던 지점이 자료에 있으면 지우지 않는다
4. **남의 말을 그대로 옮긴다** — javadoc·문서·커밋 메시지·사용자 문의. 요약하지 않는다
5. **자료에 남은 오독을 그 자리에 둔다** — 누군가 실제로 틀리게 읽었다는 기록(버그·정정·문의)이 있을 때만.
   독자가 틀릴 것이라고 가정해서 만든 「~로 읽기 쉽다」는 이 항목이 아니라 지어낸 독자다

다섯을 다 쓰지 않는다. 한 기록에 둘이면 충분하고 **하나도 없어도 된다.** 이미 충분히 설명된 문단에
사람의 목소리를 더하려고 문장을 붙이면 그것이 「설명 뒤의 평가」가 된다. 다섯을 채우면 그것이 또 다른 틀이 된다.

## 문체는 옮기지 않는다

참고 글은 합니다체이고 `~는데요`·`~텐데요`·`~거든요`로 말을 부드럽게 한다. 이 저장소의 기록은
한다체다. **부드러움을 흉내 내면 그 회사 목소리가 되고, 기록의 어조가 무너진다.**

한다체에서 사람이 드러나는 자리는 어미가 아니라 **무엇을 말하기로 했는가**다.

```text
없는 목소리    컨트롤러가 직접 내부 토큰을 확인한다.
지어낸 목소리  컨트롤러가 직접 내부 토큰을 확인하는데요, 이게 좀 아쉬운 부분입니다.
평가만 더한 것 컨트롤러가 직접 내부 토큰을 확인한다. 지금 구조에서 이것을 막는 것은 없다.
있는 목소리    컨트롤러가 직접 내부 토큰을 확인한다. /edge/** 전체를 보호하는 filter 는 없어서,
              새 엔드포인트가 같은 메서드를 부르지 않으면 그 엔드포인트는 검사를 지나친다.
```

네 번째가 사람이 쓴 글이다. 어미는 그대로이고, 아는 사람만 할 수 있는 말이 하나 붙었다 — 그리고 그
말이 **사실을 더한다**(filter 가 없다, 어느 경로가 검사를 지나치는가). 세 번째처럼 판정만 더하면
(「막는 것은 없다」) 그것은 목소리가 아니라 평가다. 그런 문장은 빼는 쪽이 맞다.

## 절차

1. **자료를 먼저 훑는다.** 위 표의 자리를 다 열고, 쓸 수 있는 흔적을 목록으로 적는다
2. **흔적이 없으면 멈춘다.** 문서에 그렇게 보고한다
3. **흔적마다 놓일 자리를 정한다.** 대개 그 주장이 나오는 문단 바로 뒤다
4. **옮긴다.** 문장을 새로 짓지 말고, 자료의 말을 그 자리에 놓는 것으로 시작한다
5. **검사한다** — `scripts/check_voice.mjs`. 이 검사기는 목소리가 **모자란지** 재지 않는다.
   **지어낸 목소리**를 잡는다
6. `../rewriting-technical-prose-naturally`의 `check_prose.mjs`를 다시 돌린다

## 검사

```bash
node .agents/skills/writing-as-the-person-who-did-it/scripts/check_voice.mjs <파일.md>
```

세 가지를 본다.

- **지어낸 경험** — 자료가 뒷받침하지 않으면 error인 표현들
- **참고 글에서 옮겨 온 인사말** — 「도움이 되길 바랍니다」 계열
- **합니다체 부드러움을 한다체에 섞은 자리**

검사기가 조용하다고 목소리가 생긴 것은 아니다. **모자란 것은 사람이 읽어야 안다.**

## 참조

- [references/voice-moves.md](references/voice-moves.md) — 다섯 가지가 여섯 편에서 어떻게 쓰였나
- `../rewriting-technical-prose-naturally/examples/` — 원문 여섯 편
- `../rewriting-technical-prose-naturally/references/article-shape.md` — 밀도. 이 스킬보다 먼저 본다
- `../writing-tech-log-records/references/writing-each-kind.md` — 종류마다 어느 칸이 사람의 자리인가