document-haness/.agents/skills/writing-as-the-person-who-did-it/SKILL.md

name, description

name	description
writing-as-the-person-who-did-it	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.

일한 사람이 쓴 글로 만들기

무엇을 고치는 스킬인가

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

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

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

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

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

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

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

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

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

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

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

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

옮길 수 있는 다섯 가지

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

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

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

문체는 옮기지 않는다

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

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

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

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

절차

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

검사

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

세 가지를 본다.

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

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

참조

• 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 — 종류마다 어느 칸이 사람의 자리인가