chore: snapshot working tree before harness removal

미추적 파일과 미커밋 수정을 전부 담아 pre-harness-removal 태그의 복구 범위를 확보한다. .agents/skills/writing-natural-korean 9개와 korean-technical-blog-skills-bundle-v1 61개가 여기 포함된다. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-07 14:19:24 +09:00
parent b101b6e717
commit 1099834617
85 changed files with 8547 additions and 114 deletions
@@ -0,0 +1,42 @@
+# 판단 우선순위와 불변식
+
+## 우선순위
+
+1. 사실·법무·보안·코드·직접 인용
+2. 사용자 요구와 프로젝트·기업의 공식 가이드
+3. 공식 제품명과 프로젝트 용어
+4. 한국어 어문 규범
+5. 기술 독자의 이해와 접근성
+6. 기술 블로그 장르 구조
+7. AI 유사 문체 완화
+8. 미적 변주와 개성 강화
+
+하위 규칙이 상위 규칙을 침해하면 하위 수정을 취소한다.
+
+## 불변식
+
+- 긍정·부정, 조건, 예외, 시제, 시간 순서
+- 가능성·권고·의무·확정의 강도
+- 주체, 객체, 책임 범위와 1인칭 관점
+- 수치, 단위, 날짜, 버전, 오류 코드와 지표 정의
+- 기술 선택의 이유, 비교한 대안, 비용과 위험
+- 실험 환경, 표본, 미측정 상태와 불확실성
+- 제품명, 기술명, API·클래스·함수·설정 키
+- 코드, 명령어, URL, 직접 인용, 법무·보안 문구
+- 마크다운의 코드 블록, 표, 목록과 링크 구조
+
+## 즉시 실패
+
+- 원문에 없는 수치·성과·사례·감정·사용자 반응 생성
+- 코드·명령어·법무 문구·직접 인용 변경
+- 민감 정보 또는 미공개 정보를 그대로 공개
+- 불리한 결과, 실패 조건, 비용 또는 위험 삭제
+- 미측정 결과를 검증된 결과처럼 작성
+- 작성 주체가 불명확한데 임의로 개인이나 팀에 책임 부여
+
+## 정보 부족
+
+- 글의 목적·독자·문서 유형이 없어도 안전한 기본값으로 진행할 수 있으면 가정 목록에 기록한다.
+- 사실 여부나 구조를 바꾸는 필수 정보가 없으면 한 번에 필요한 최소 질문만 하거나 `[확인 필요]`로 남긴다.
+- 선택적인 배경·회고·성과 정보가 없으면 해당 섹션을 생략한다.
+- 자료끼리 충돌하면 더 높은 우선순위의 출처를 사용하고 충돌을 경고한다.
@@ -0,0 +1,29 @@
+# 기업 기술 블로그에서 재현할 구조적 패턴
+
+이 문서는 특정 기업의 문체를 모방하기 위한 자료가 아니다. 업로드된 연구가 NAVER D2, 카카오, LINE, 우아한형제들, 삼성SDS의 공개 글에서 추출한 **구조적 특징**만 일반화한다.
+
+## 재현할 가치가 큰 패턴
+
+- `성능이 좋아졌다`보다 지표 정의와 전후 수치를 제시한다.
+- 측정·관찰 단계와 개선·적용 단계를 분리한다.
+- 도입 계기에서 아키텍처와 실제 시나리오까지 독자의 판단 순서로 전개한다.
+- 정량 목표를 먼저 정하고 분석·조치·재측정으로 이어 간다.
+- 여러 시도를 하나의 묘책처럼 합치지 않고 각 가설과 결과를 분리한다.
+- 성공 결과뿐 아니라 테스트 설계, 운영 비용, 실패 조건과 교훈을 남긴다.
+- 실험 환경과 비교 기준을 공개해 수치의 적용 범위를 드러낸다.
+- 사용자 화면에 보이지 않는 이관·인프라 작업은 왜 필요했는지부터 설명한다.
+- 기존 기술의 기대 효과와 실제 워크로드에서 얻지 못한 효과를 대조한다.
+- 표와 참고문헌은 핵심 명제를 검증 가능하게 만드는 경우에만 사용한다.
+
+## 피해야 할 패턴
+
+- 추상적인 미래·혁신 은유로 결론을 대신함
+- 범위·시점·근거가 없는 전망
+- 한 문장에 개발·품질·위험·확장성 효과를 모두 중첩
+- `도움이 되기를 기대합니다` 같은 의례적 마무리
+- 검증 불가능한 최상급과 감탄 표현
+- 브랜드 친근함을 이유로 기술적 경고나 비용을 약화
+
+## 브랜드 적용
+
+프로젝트의 명시적 스타일 가이드가 있으면 이를 우선한다. 가이드가 없으면 다른 기업의 어휘·유머·말투를 흉내 내지 않고, 정확·명료·절제된 기본 문체를 사용한다.
@@ -0,0 +1,38 @@
+# 근거와 출처 처리
+
+## 주장 유형
+
+각 핵심 문장을 다음 중 하나로 분류한다.
+
+| 유형 | 의미 | 작성 방식 |
+|---|---|---|
+| source | 제공된 자료에 직접 있음 | 자료의 범위와 표현 강도를 유지 |
+| external | 외부 출처가 있음 | 출처와 적용 범위를 함께 표시 |
+| observed | 작성자 또는 팀이 관찰함 | 환경·기간·측정 방법을 함께 기록 |
+| inferred | 자료를 바탕으로 추론함 | 추론임을 명시하고 근거를 연결 |
+| unverified | 아직 확인하지 않음 | `[확인 필요]`, 미측정 또는 예정으로 표시 |
+
+## 근거 지도
+
+초안 전 최소한 다음 표를 내부적으로 만든다.
+
+```text
+주장 | 근거 위치 | 신뢰 수준 | 보호 요소 | 공개 가능 여부
+```
+
+정량 주장은 수치만 남기지 말고 지표 정의, 측정 기간, 환경, 비교 기준과 제외 조건을 가능한 범위에서 함께 기록한다.
+
+## 외부 자료
+
+사용자가 외부 조사나 검증을 요청하지 않았다면 제공된 자료 밖의 지식을 사실처럼 채우지 않는다. 외부 조사를 수행했다면 소스 기반 내용과 외부 조사 내용을 분리하고 인용을 붙인다.
+
+## 코드와 명령어
+
+- 코드와 명령어는 자연어 편집 대상에서 제외한다.
+- 실행 결과가 제공되지 않았으면 `검증했다`, `정상 동작한다`고 쓰지 않는다.
+- 코드 설명은 코드가 실제로 하는 일을 넘어서지 않는다.
+- 예제 코드가 축약되거나 의사 코드이면 그 사실을 표시한다.
+
+## 민감 정보
+
+계정, 비밀 키, 토큰, 내부 도메인·IP, 개인정보, 미공개 장애 정보, 고객 식별자는 공개 글에 포함하지 않는다. 자동 마스킹으로 의미가 손상될 수 있으면 `blocked` 상태와 필요한 조치를 반환한다.
@@ -0,0 +1,28 @@
+# 경계와 예외
+
+| 상황 | 잘못된 처리 | 올바른 처리 |
+|---|---|---|
+| 성능이 좋아졌지만 수치 없음 | 임의의 백분율 추가 | 관찰 환경과 미측정 상태 명시 |
+| 행위자 미확정 | 능동태를 위해 운영자 지정 | 피동을 유지하고 주체 미확정 표시 |
+| 직접 인용에 구어체·오탈자 | 기술 문체로 바꿈 | 인용문은 보존하고 밖에서 설명 |
+| 코드 주석의 비표준 표현 | 코드와 함께 자동 교정 | 실행 코드 보호, 변경 허용된 자연어 주석만 별도 검토 |
+| 영문 기술명 혼용 | 임의로 한글화 | 공식 표기 확인, 불가하면 첫 표기 유지 + 경고 |
+| 해요체 원문 | 무조건 합니다체로 통일 | 일관된 원문 말투 유지 |
+| 감성적 글을 요청 | 경험·감정 창작 | 자료에 있는 관찰과 감정만 사용 |
+| 핵심 용어 반복 | 동의어로 무작위 변경 | 기술 용어는 유지하고 주변 구조를 조정 |
+| 결론 중복 제거 | 한계·재발 방지까지 삭제 | 단순 재요약만 줄임 |
+| 보안·장애 공지 | 친근함을 위해 심각성 완화 | 위험 전달과 정확성 우선 |
+
+## 질문 대신 진행할 수 있는 경우
+
+- 독자가 미지정이면 기본 독자 가정을 밝히고 진행
+- 말투가 미지정이면 원문을 유지하거나 기본 합니다체 사용
+- 선택 절의 정보가 없으면 생략
+- 일부 근거만 부족하면 해당 주장에 `확인 필요`를 붙이고 나머지 작성
+
+## 중단 또는 차단할 경우
+
+- 핵심 수치나 결과가 서로 충돌함
+- 소스에 없는 주장을 반드시 사실처럼 쓰라고 요구함
+- 공개하면 안 되는 정보가 글의 핵심임
+- 법적 고지나 인용을 변조해야만 요청을 만족함
@@ -0,0 +1,48 @@
+# 출력 모드
+
+## article — 기본
+
+완성된 제목과 본문을 먼저 제공한다. 근거 부족이나 공개 위험이 있을 때만 짧은 경고를 덧붙인다.
+
+## outline
+
+자료를 쓰지 않고 다음을 출력한다.
+
+- 글의 목적과 독자
+- 핵심 주장과 근거
+- 선택한 프로필
+- 제목 후보
+- 섹션별 메시지와 필요한 자료
+- 확인이 필요한 항목
+
+## audit
+
+원문을 수정하지 않는다. 구조, 근거, 불변식, 보호 구간, 기술적 설명력, 문체 위험과 공개 위험을 심각도순으로 진단한다.
+
+## revision
+
+수정본을 먼저 제시하고 주요 변경을 `문제 → 수정 → 규칙 ID → 보존 확인` 형식으로 기록한다.
+
+## compare
+
+원문과 수정문을 대응시켜 보여 준다. 문장 전체를 모두 설명하지 않고 의미 있는 구조·근거·보존 관련 변경만 기록한다.
+
+## publication-package
+
+요청이 있을 때만 다음을 포함한다.
+
+- 제목 3개 이하
+- 한 문단 요약
+- 본문
+- 메타 설명
+- 태그 후보
+- 근거·인용 목록
+- 공개 전 확인 항목
+
+SEO 키워드 반복, 클릭 유도형 제목, 근거 없는 성과 문구는 추가하지 않는다.
+
+## 상태
+
+- `pass`: 자료 범위 안에서 결과를 작성함
+- `needs_clarification`: 필수 사실 또는 공개 범위가 불명확함
+- `blocked`: 민감 정보, 법무·보안 위험 또는 보호 구간 훼손 없이는 작성할 수 없음
@@ -0,0 +1,72 @@
+# 규칙 카탈로그
+
+이 문서는 스킬의 판단 규칙과 테스트 ID를 연결한다. 규칙 충돌 시 `references/decision-policy.md`의 우선순위를 따른다.
+
+### INV-01 — 수치·날짜·버전·단위 보존
+원문에서 숫자와 대응 대상을 추출하고 출력에서 같은 관계를 유지한다. 값, 방향, 단위, 기간을 임의로 바꾸지 않는다.
+
+### INV-02 — 보호 구간 잠금
+코드 블록, 인라인 코드, 명령어, URL, 직접 인용, 법무·보안 문구, 사용자가 잠근 문자열은 정확히 보존한다.
+
+### INV-03 — 공식 용어 표기표
+제품명, 기술명, 팀명, 약어와 식별자의 기준 표기를 먼저 정하고 글 전체에서 일관되게 사용한다.
+
+### SRC-01 — 원문 밖 사실 생성 금지
+자료에 없는 성과, 원인, 사용자 반응, 업계 추세, 감정과 경험을 만들지 않는다.
+
+### SRC-02 — 미지정 정보의 명시
+필수 정보가 없으면 `[확인 필요: ...]`, 미지정, 미측정 또는 질문으로 남긴다. 선택 섹션은 생략한다.
+
+### AUD-01 — 목적·독자·독자 결과 확인
+글을 쓰기 전에 왜 쓰는지, 누가 읽는지, 읽고 무엇을 이해하거나 결정해야 하는지 고정한다.
+
+### STR-01 — 기술 사례 기본 골격
+자료가 뒷받침하는 범위에서 문제·맥락 → 제약·대안 → 선택 → 구현·실험 → 결과 → 한계·후속 조치로 구성한다.
+
+### STR-02 — 핵심 결과의 조기 제시
+결과 수치가 글의 핵심이면 첫 15% 안의 요약이나 도입에 배치하고 측정 환경과 함께 제시한다.
+
+### STR-03 — 대상과 행동이 드러나는 제목
+`소개`, `살펴보기`, `여정`만으로 제목을 만들지 않는다. 대상, 문제, 선택 또는 결과를 제목에 드러낸다.
+
+### KOR-01 — 한국어 규범 최종 검수
+초안과 문체 편집이 끝난 뒤 `editing-korean-grammar-and-expression`으로 맞춤법·띄어쓰기·문장 부호를 검수한다.
+
+### KOR-02 — 문장 호응과 수식 범위
+주어·목적어·서술어의 호응을 확인하고 독립 주장·조건·결론이 한 문장에 과도하게 중첩되면 의미를 보존해 분리한다.
+
+### KOR-03 — 식별자와 일반 개념 구분
+코드 식별자와 공식 제품명은 원문을 보존한다. 일반 기술 개념은 필요할 때 첫 등장에 한국어 설명을 붙인다.
+
+### CLR-01 — 주체와 동작 우선
+추상 명사와 막연한 평가보다 누가 무엇을 했고 어떤 영향이 있었는지 쓴다. 근거가 없으면 구체화를 보류한다.
+
+### CLR-02 — 복합 문장 분리
+독립 주장·조건·결론이 셋 이상이거나 검증 관계가 흐려지면 문장을 나누거나 표·목록으로 옮긴다.
+
+### CLR-03 — 모호한 지시어 복원
+`이를`, `이러한`, `해당`, `이것`의 선행 대상이 불명확하면 자료에 있는 구체 명사를 복원한다.
+
+### AI-01 — 실제 문제로 시작
+시대 일반론, 의례적 인사, 글쓰기 행위 설명보다 시스템의 문제, 관찰값, 목표 또는 독자가 얻을 정보를 먼저 제시한다.
+
+### AI-02 — 평가어를 근거로 대체
+`중요하다`, `효율적이다`, `혁신적이다`, `빠르다`는 지표·작동 방식·영향·비교 기준이 있을 때만 사용한다.
+
+### AI-03 — 구조와 문장 틀 반복 완화
+접속어와 종결형을 무작위로 바꾸지 않는다. 실제 인과·시간·비교 관계에 맞춰 반복을 줄인다.
+
+### AI-04 — 결과·한계 중심 결론
+결론은 본문 재요약이나 의례적 기대보다 결정, 검증 결과, 적용 조건, 남은 문제와 다음 검증을 제시한다.
+
+### AI-05 — 인간 흉내 금지
+자연스럽게 보이게 하려고 오탈자, 비문, 감정, 실패담, 사적 일화나 확신을 만들지 않는다.
+
+### BRD-01 — 프로젝트·기업 프로필 우선
+명시된 브랜드 가이드가 있으면 우선한다. 없으면 다른 기업을 모방하지 않고 정확·명료·절제된 기본 프로필을 사용한다.
+
+### REV-01 — 변경 근거 기록
+수정 모드에서는 주요 변경마다 문제, 수정 결과, 규칙 ID, 보존 확인과 필요한 경고를 기록한다.
+
+### TST-01 — 하드 게이트와 회귀 검증
+사실 변경, 보호 구간 변경, 허위 근거, 보안 노출은 점수와 무관하게 실패다. 일반·어려운·회귀 사례를 모두 검증한다.
@@ -0,0 +1,34 @@
+# 자료 근거
+
+이 스킬은 사용자가 제공한 연구 문서 `붙여넣은 마크다운(1)(2).md`의 내용을 기반으로 구성했다. 문서에 포함된 다음 범주의 자료와 사례를 규칙·프로필·테스트로 변환했다.
+
+- 국립국어원 한국어 어문 규범, 맞춤법·표준어·문장 부호·공공언어 자료
+- 토스의 라이팅 원칙, 테크니컬 라이팅 Skill 구현과 Skill 품질 루브릭 사례
+- Google Developer Documentation Style Guide
+- Microsoft Writing Style Guide
+- 한국어 LLM 문체 관련 ACL 2025 연구
+- NAVER D2, 카카오, LINE, 우아한형제들, 삼성SDS의 공개 기술 글 사례 분석
+
+## 출처 계층
+
+1. 사실·법무·보안·코드·직접 인용
+2. 프로젝트 또는 기업의 명시적 가이드
+3. 공식 제품명과 기술 용어
+4. 국립국어원 공식 규범
+5. 기술 독자의 이해와 접근성
+6. 기술 블로그 장르 관습
+7. AI 유사 문체 완화
+8. 미적 변주
+
+## 원문이 제시한 주요 링크
+
+- https://korean.go.kr/kornorms
+- https://developers.google.com/style
+- https://learn.microsoft.com/en-us/style-guide/welcome/
+- https://toss.tech/article/8-writing-principles-of-toss
+- https://toss.tech/article/technical-writing-5
+- https://toss.tech/article/skill-quality-rubric
+- https://aclanthology.org/2025.acl-long.1030/
+- https://aclanthology.org/2025.acl-long.267/
+
+이 패키지는 링크의 최신 상태나 원 연구의 해석을 별도로 재검증하지 않았다. 스킬 내용은 업로드된 연구가 정리한 범위에 한정된다.
@@ -0,0 +1,56 @@
+# 기술 블로그 구조 패턴
+
+목차를 고정 템플릿처럼 강제하지 않는다. 독자가 따라야 할 의사결정 순서를 기준으로 프로필을 선택한다.
+
+## 공통 골격
+
+1. 문제 또는 관찰값
+2. 왜 지금 해결해야 했는지
+3. 제약과 성공 기준
+4. 검토한 대안과 선택 이유
+5. 구현·실험 또는 운영 방식
+6. 검증 방법과 결과
+7. 비용·한계·실패 조건
+8. 남은 과제와 적용 조건
+
+자료가 없는 섹션은 만들지 않는다. 결과가 핵심이면 도입부에서 먼저 보여 주고 뒤에서 측정 방법을 설명한다.
+
+## 도입
+
+첫 15% 안에 다음 중 필요한 내용을 드러낸다.
+
+- 어떤 시스템이나 작업을 다루는지
+- 실제 문제 또는 관찰값
+- 독자가 얻을 수 있는 정보
+- 핵심 결과와 측정 범위
+
+피해야 할 시작은 시대 일반론, 의례적 인사, `이번 글에서는 살펴보겠습니다`뿐인 문장이다.
+
+## 제목
+
+제목은 대상·문제·행동·선택·결과 중 하나 이상을 담는다.
+
+```text
+나쁨: Kubernetes 배포 자동화 소개
+개선: Kubernetes 배포에서 승인·롤백·상태 확인을 자동화한 방법
+```
+
+숫자를 제목에 넣을 때는 본문이 같은 측정 기준을 뒷받침해야 한다.
+
+## 본문
+
+- 기술 선택은 장점 목록보다 제약과 대안 비교로 설명한다.
+- 실험은 환경, 입력, 지표, 전후 조건을 분리한다.
+- 여러 시도는 가설·조치·결과를 각각 묶는다.
+- 보이지 않는 인프라 작업은 `왜 해야 했는가`부터 설명한다.
+- 구현 세부는 독자가 재현하거나 판단하는 데 필요한 수준까지만 포함한다.
+
+## 결론
+
+결론은 본문을 다시 요약하는 대신 다음을 선택한다.
+
+- 실제 결과와 측정 범위
+- 선택이 유효한 조건
+- 남은 비용과 위험
+- 실패한 가설 또는 얻은 교훈
+- 다음에 측정하거나 바꿀 항목
@@ -0,0 +1,43 @@
+# 제목·도입·결론
+
+## 제목
+
+대상과 행동 또는 갈등을 드러낸다.
+
+| 약한 제목 | 개선 방향 |
+|---|---|
+| Kubernetes 살펴보기 | Kubernetes로 배포 롤백을 자동화한 방법 |
+| 성능 개선 이야기 | 검색 API p95를 420ms에서 180ms로 줄인 과정 |
+| Kafka 도입기 | 장시간 작업에서 Kafka 대신 RDB Task Queue를 선택한 이유 |
+
+수치 제목은 근거와 범위가 명확할 때만 사용한다.
+
+## 도입
+
+첫 15% 안에 다음 세 가지를 드러낸다.
+
+1. 어떤 시스템·작업에서 무슨 문제가 있었는가
+2. 왜 독자에게 중요한가 또는 어떤 제약이 있었는가
+3. 글을 읽으면 무엇을 알 수 있는가
+
+시대 일반론, 의례적 인사, ‘여정을 살펴보겠다’는 메타 문장으로 시작하지 않는다.
+
+## 소제목
+
+`소개`, `배경`, `내용`, `결론`만 쓰지 말고 절의 판단이나 동작을 표현한다.
+
+- `배경` → `배포가 18분 걸린 이유`
+- `구현` → `실패 단계를 분리해 로그를 남기기`
+- `결과` → `평균 배포 시간은 줄었지만 승인 대기는 남았다`
+
+## 결론
+
+다음 중 실제 자료가 있는 항목으로 끝낸다.
+
+- 어떤 결정을 내렸는가
+- 어떤 결과를 어떤 조건에서 확인했는가
+- 무엇은 해결하지 못했는가
+- 어디까지 적용 가능한가
+- 다음에 무엇을 측정하거나 바꿀 것인가
+
+본문을 다시 요약하거나 ‘더 나은 미래’, ‘많은 것을 배웠다’, ‘지속적으로 발전시키겠다’로 끝내지 않는다.