스킬 일반화와 검사

프로젝트 안에서 자란 스킬은 잘 작동한다. 그 프로젝트에서만 잘 작동한다.
이 스킬은 거기서 어디서나 성립하는 부분만 떼어내는 절차다.

새로 작성하는 것이 아니라 이미 있는 것을 가르는 작업이다.

두 가지 일을 다룬다.

	절	내용
일반화	§1 · §2 · §3 · §4 · §7 · §8	무엇을 남기고 무엇을 옮길지 가른다
검사	§4-1 · §5 · §6	열어 읽기 · 상호참조 · 식별 정보

검사 절들은 일반화할 때뿐 아니라, 스킬을 새로 만들거나 고친 뒤에도 따로 쓴다.
그중 §4-1(열어 읽기)이 나머지 둘을 대신할 수 없고, 반대도 마찬가지다.

1. 스킬은 3층이 섞여 있다

일반화의 전부는 문장마다 어느 층인지 판별하는 것이다.

층	정체	갈 곳
방법론	어느 프로젝트에서도 참인 절차·원칙·교훈	스킬에 남긴다
그때의 결정	특정 시점·팀·자원 상황에서 나온 판단	프로젝트 문서로 옮긴다
환경 고유값	경로·문서 ID·계정·모델명	인자·설정으로 뺀다

판별 질문은 하나다.

다음 프로젝트에서도 이 문장이 참인가?

• 항상 참 → 방법론
• 이번엔 참, 다음엔 아닐 수 있음 → 결정. 스킬에는 "그 프로젝트의 문서를 따른다" 만 남긴다
• 기계가 읽는 값 → 파라미터

결정이 섞여 있는 신호

이런 문장을 보면 2층이다. 근거가 그 시점의 사정에 있다.

• 특정 수치가 이유 없이 박혀 있다 — "총 100장", "상한 1만 장"
• 특정 인물·직책의 지시가 근거다 — "PM 확정", "담당자 지시로 변경"
• 특정 장비·계정을 전제한다 — "로컬 1GPU 단독", "서버 이관은 검토 대상 아님"
• 날짜가 붙은 확정 문구다 — "2026-XX-XX 확정, 변경 없는 한 계속 적용"

이 문장들은 틀린 게 아니라 유효기간이 있는 것이다. 지우지 말고 프로젝트 문서로 옮긴다.

2. 스킬이 프로젝트 상태를 들고 있으면 즉시 분리한다

가장 흔하고 가장 해로운 형태다. 스킬 본문에 이런 절이 있는 경우다.

## 현재 상태 스냅샷 (YYYY-MM-DD 기준)
- 주력 모델 = ... 채택 제안. 최종 승인은 확인 필요
- ... 환경 전 구간 완료

스킬은 "어떻게 하는가"만 담는다. 상태는 진행상황 문서가 가진다.
스냅샷을 스킬에 두면 갱신되지 않고, 다음 세션이 몇 주 지난 사실을 최신인 줄 알고 읽는다.
일반화 여부와 무관하게 당장 떼어내야 하는 결함이다.

3. 노하우는 반드시 남긴다 — 일반화는 "짧게 만들기"가 아니다

가장 자주 망치는 지점이다. 고유명사를 걷어내다 보면 문장이 점점 추상적으로 변하고,
결국 누구나 아는 원칙만 남은 껍데기가 된다. 그 스킬을 읽을 이유가 사라진다.

스킬의 값어치는 구체성에 있다. 다음 셋은 일반화 대상이 아니라 보존 대상이다.

① 실패 사례와 교훈

교훈은 어디서 겪었는지와 무관하게 성립한다.

지움  X  "A프로젝트에서 겪은 실제 사고다"   → 사례 자체를 삭제
남김  O  "실제 운영에서 겪은 사고다"        → 과제명만 제거, 내용 유지

무엇이 어떻게 실패했는가가 본체이고, 어디서 겪었는가는 장식이다.
"에러는 0건이었다", "개별 검사는 전부 통과했다" 같은 정황 묘사도 함께 남긴다 —
그게 없으면 왜 못 잡았는지가 전달되지 않는다.

② 실행 예시 — 명령·인자·형식

명령 예시를 지우면 읽는 쪽이 처음부터 다시 알아내야 한다.
경로·계정만 갈아끼우고 명령 형태와 인자 구조는 그대로 둔다.

# 지움  X   "적절한 인자로 실행한다"
# 남김  O
python <스크립트> --model <모델명> --stage extract|train|eval
#   산출: results/<대상>_<모델>_<단계>.json, 로그 results/logs/run.log

산출 파일명 규칙, 폴더 구조, 보고서 골격 같은 형식 템플릿도 예시다. 남긴다.

③ 함정과 그 증상

"이렇게 하면 이런 오류가 난다"는 지식은 겪어야만 얻어진다.
증상 문자열·종료 코드·재현 조건까지 함께 남긴다.

남김  O  옵션은 서브커맨드 앞에 와야 한다.
         순서를 바꾸면 `unexpected argument` 로 exit 2.

판별 질문

이 문장을 지우면, 읽는 사람이 무엇을 못 하게 되는가?

• 아무것도 못 하게 되지 않음 → 지워도 되는 장식
• 다시 알아내야 함 → 노하우다. 남긴다

일반화 후 스킬이 눈에 띄게 짧아졌다면, 대개 줄인 게 아니라 잃은 것이다.
분량이 줄어야 하는 건 §1의 2층(그때의 결정)뿐이고, 노하우는 그대로여야 한다.

4. 기계 치환은 쓰지 않는다

"프로젝트 A용 사본을 만들자"며 문자열을 일괄 치환하면 고유명사까지 함께 바뀐다.
실제로 이런 파손이 관측됐다.

제품 도메인이 치환되어 존재하지 않는 도메인이 됨
설정 폴더 경로가 치환되어 존재하지 않는 경로가 됨

치환은 에러를 내지 않는다. 그 스킬을 읽은 에이전트가 없는 경로를 찾다 실패할 때까지 조용하다.
일반화는 문장 단위로 판단해서 다시 쓰는 작업이지, 검색·치환이 아니다.

4-1. 검사는 파일을 하나씩 열어서 한다 — 검색으로 갈음하지 않는다

이 절이 이 스킬에서 가장 자주 무시되는 조항이다.

grep 은 내가 미리 떠올린 패턴만 찾는다. 일반화에서 정작 위험한 것은
내가 있는 줄도 몰랐던 잔재이고, 그건 정의상 검색어로 떠오르지 않는다.

실측 사례 둘. 둘 다 검색 기반 검사를 전부 통과한 뒤의 일이다.

	대상	검색으로 잡힘	열어 읽어서 잡힘
①	이관한 스킬 12개	0건	11건
②	방금 내가 새로 쓴 스킬 1개	0건	5건

②가 더 중요하다. 직접 쓴 파일이라 내용을 안다고 여겼고, 그 확신이 읽기를 대신했다.
남의 것보다 자기가 방금 쓴 것을 더 안 읽는다.

열어야만 보이는 것	실제로 나온 예
화자 전환	다른 스킬에서 가져온 문장이 정반대 지시가 됐다. "이유를 모르면 우회한다"는 원 출처에서 지시서 쓰는 쪽에게 하는 현상 서술인데, 받는 쪽 규칙으로 옮기니 "우회하라"는 명령문이 됐다
자기모순	"특정 프로젝트 경로를 적지 않는다"고 써 둔 바로 아래에 그 프로젝트의 요구 항목이 남아 있었다
절 간 용어 충돌	§4 제목이 "되돌릴 수 있게", §7 제목이 "되돌릴 수 없는 작업" — 한 문서 안에서 같은 말이 다른 뜻이었다
예시와 규칙 불일치	예시는 인자가 하나인데 파일명 규칙은 셋을 요구했다
계층 위반	항상 설치되는 공통 스킬이 선택 설치되는 스킬을 이름으로 참조하고 있었다
규약 누락	이력 절이 아예 없거나, 형식이 다르거나, 오늘 고쳐 놓고 기록하지 않았다
스테일	이력에 "스킬 3종 신설"이라 적혀 있는데 실제로는 12종이 됐다
하드코딩	대상 파일명이 특정 프로젝트의 이름으로 본문·description 양쪽에 박혀 있었다
설치 위치 가정	예시 경로가 특정 스킬 저장소를 전제하고 있었다

이 중 검색어를 미리 떠올릴 수 있었던 것은 하나도 없다.

어떻게 읽는가

• 한 파일을 처음부터 끝까지 읽는다. 절 제목만 훑지 않는다 — 잔재는 절 안쪽에 있다.
• 다른 곳에서 가져온 문장은 화자를 확인한다. 누가 누구에게 하는 말인지가 바뀌면
  같은 문장이 반대 뜻이 된다. 특히 **현상 서술("~하게 된다")과 지시("~하라")**는
  옮기는 순간 뒤바뀌기 쉽다.
• 절 제목들을 한자리에 놓고 본다. 같은 낱말이 절마다 다른 뜻으로 쓰이고 있지 않은지.
• 예시와 규칙을 서로 대조한다. 예시의 인자 개수·이름이 규칙이 요구하는 것과 같은지.
• 읽으면서 이 스킬이 사는 위치를 계속 의식한다. "이건 항상 설치되는가, 선택 설치되는가",
  "여기서 이 이름을 불러도 되는가".
• 프론트매터와 본문이 같은 말을 하는지 대조한다. description 만 옛 사실을 담고 있는 경우가 있다.
• 이력 절을 마지막에 본다. 오늘 고친 것이 적혀 있지 않으면 그 자체가 결함이다.

고친 뒤에 다시 읽는다

수정은 새 결함을 만든다. 실제로 위 5건을 고친 직후 다시 읽어 1건을 더 잡았다 —
끼워 넣은 인용문이 문단 사이를 갈라 앞뒤 문장의 연결을 끊고 있었다.

한 번 읽고 고친 뒤 끝내지 않는다. 고친 부분의 앞뒤를 다시 읽는다.

검색은 읽기 전에 후보를 좁히는 용도이거나, 읽은 뒤 놓친 게 없는지 재확인하는 용도다.
읽기를 대신하지 못한다.

5. 상호참조를 점검한다 — 린터가 못 잡는 곳

옮긴 스킬이 대상 레포에 없는 형제 스킬을 가리키면, clone한 사람은 존재하지 않는 것을 찾게 된다.

"자세한 규칙은 <다른 스킬>을 따른다"   ← 그 스킬이 같이 안 갔으면 끊긴 참조

포터빌리티 린터는 구조만 검사한다. 프론트매터·경로·줄바꿈은 보지만
"이 스킬이 가리키는 형제가 실제로 있는가"는 확인하지 않는다.
린터가 전부 통과해도 끊긴 참조는 남아 있을 수 있으므로 따로 확인한다.

⚠️ 참조는 한 가지 형태로만 쓰이지 않는다

[[이름]] 만 훑으면 놓친다. 실제로 링크 형태를 전수 검사해 "전부 실존"을 확인한 뒤에도,
백틱으로 적힌 이름이 남아 있었다.

잡힘   [[어떤-스킬]]         ← 링크 형태
놓침   `어떤-스킬` 업무을     ← 백틱 형태. 같은 참조인데 검사에서 빠진다
놓침   어떤-스킬 을 따른다    ← 맨 이름

→ 이름 자체를 문자열로 검색한다. 특히 이름을 바꿨다면 옛 이름 전수 검색이 필수다.
링크 형태만 고치고 산문 속 옛 이름을 남기면, 읽는 쪽은 없는 스킬을 찾는다.

⚠️ 반대로 자리표시자는 오탐이다. 문서에서 규약을 설명하는
`[[skill-name]]` 로 참조합니다 같은 문장은 실제 참조가 아니다. 검사 결과를
그대로 믿지 말고 어디서 나온 것인지 확인한다.

고치는 방법은 둘이다.

1. 역할로 지칭 — "재현 절차 스킬", "보고서 스킬"처럼 이름 대신 역할로 쓴다
2. 함께 옮긴다 — 참조 대상이 없으면 반쪽인 스킬이면 묶어서 옮긴다

6. 공개 전 식별 정보 스캔 (필수)

공개 레포로 올린다면 되돌릴 수 없다. 공개 시점에 크롤링·캐시될 수 있다.
올리기 전에 반드시 훑는다.

• 조직·과제·제품명, 대상 도메인
• 인물 이름·직책·호칭
• 절대 경로, 사용자 계정명
• 문서 ID·URL·채널명
• 내부 모델·시스템 식별자
• 자격증명 흔적 (api_key, token, password, secret)

한 번 훑고 끝내지 않는다. 일반화 편집을 한 뒤 다시 훑는다 — 고치는 과정에서
새로 들어가기도 한다.

7. 원본을 어떻게 할지 정한다

일반화본을 공용 레포에 올린 뒤, 원래 자리의 사본을 그대로 두면 사본이 둘이 된다.
셋 중 하나를 고른다.

선택	언제
링크(정션/심링크)	프로젝트가 일반화본을 그대로 써도 될 때 — 가장 깔끔
스텁	그 자리에 있으면 안 되지만 이름으로 찾아올 수 있을 때. "여기 없다 + 어디로 가라"만 남긴다
분리 유지	프로젝트판이 정말로 달라야 할 때. 왜 다른지를 양쪽에 적는다

같아야 하는데 복사본 두 개는 고르지 않는다. 반드시 어긋난다.

8. 미리 추상화하지 않는다

두 번째 사용처가 실제로 생기기 전에 파라미터를 뽑지 않는다.
사례가 하나뿐이면 무엇이 가변인지 알 수 없고, 쓰지도 않을 설정 항목만 늘어난다.

• 사용처가 하나 → 지금은 그대로 둔다
• 둘 → 그때 갈라낸다. 무엇이 달라지는지 그제야 보인다

예외: 값 하나만 인자로 빼면 끝나는 경우는 지금 해도 된다(문서 ID, 대상 경로 등).
추상화 비용이 거의 없기 때문이다.

절차 요약

0. 파일을 하나씩 처음부터 끝까지 읽는다 — 검색으로 갈음하지 않는다(§4-1)
1. 문장마다 3층 분류 (방법론 / 결정 / 고유값)
2. 상태 스냅샷이 있으면 먼저 떼어낸다
3. 2층을 프로젝트 문서로 옮기고, 스킬엔 "그 문서를 따른다"만 남긴다
4. 3층을 인자·설정으로 뺀다 (단 §8)
5. 노하우(사례·실행 예시·함정)는 유지하고 고유명사만 제거 — §3
6. 끊긴 상호참조 점검
7. 식별 정보 스캔 → 편집 → 다시 스캔
8. 포터빌리티 린터가 있으면 통과시킨다
9. 다시 하나씩 열어 읽는다 — 고치는 과정에서 새 모순이 들어간다
10. 이력 절에 오늘 무엇을 왜 바꿨는지 기록한다
11. 원본 처리 방식 결정 (링크 / 스텁 / 분리)

마지막 확인: 일반화 전후 분량을 비교한다. 크게 줄었다면 §3을 어겼는지 되짚는다.
줄어야 할 것은 "그때의 결정"뿐이다.

관련 도구

• 포터빌리티 린터(check_skill.py)가 있는 레포라면 8단계에서 사용한다.
  구조 검사 전용이므로 §5의 상호참조 점검을 대체하지 못한다.
• 옮긴 뒤 문서 갱신은 [[progress-log]], 결과 검증은 [[work-review]].

이력 (필수 기록)

• 생성일: 2026-08-27
• 업데이트 횟수: 2
• 최근 업데이트: 2026-08-27
• 사용 이력:
  • 2026-08-27 — §4-1 보강. 새로 만든 스킬 1개를 열어 읽어 5건을 더 잡은 사례를
    두 번째 데이터로 넣었다(검색으로는 0건). 이쪽이 더 중요한 이유는 직접 쓴 파일이라
    안다고 여겼고 그 확신이 읽기를 대신했기 때문이다. 새 결함 유형 3종(화자 전환,
    절 간 용어 충돌, 예시-규칙 불일치)과 "고친 뒤 다시 읽는다"를 본문에 추가.
    또한 검사 절차가 일반화 스킬 안에만 있어 "스킬 검사해줘"로는 발동하지 않는 것이
    확인되어 description 에 점검 트리거를 넣었다.
    이 갱신 직후 스스로 §4-1을 적용해 자기 결함 3건을 잡았다 — description 이
    "점검한다"로 바뀌었는데 제목·도입부는 일반화만 말하고 있었고(프론트매터↔본문 불일치),
    description 에만 마크다운 볼드가 들어가 다른 11개와 규약이 어긋났고, 새로 쓴
    절 범위(§1~3, §6~8)가 실제 절 구성과 달랐다(예시↔규칙 불일치).
    세 가지 다 이 문서가 방금 추가한 조항에 스스로 걸린 것이다.
  • 2026-08-27 — §4-1(직접 열어 읽기) 추가. 만든 당일, 이 스킬의 다른 조항을 검색으로만
    확인하고 "전부 통과"라고 보고했는데 사용자가 "하나씩 열어서 확인해야 한다"고 지적했다.
    실제로 열어 보니 11건이 더 있었고 검색으로 잡힌 것은 0건이었다. 검색은 미리
    떠올린 패턴만 찾으므로, 모르는 잔재에는 원리적으로 닿지 못한다.
  • 2026-08-27 — 신규 생성. 프로젝트 스킬 12종을 공용 레포로 옮기려다,
    "무엇이 방법론이고 무엇이 이번 과제의 결정인가"를 매번 즉흥으로 판단하고 있음을
    발견해 절차로 굳혔다. §4(기계 치환 파손)·§2(스킬이 상태를 들고 있음)·§5(린터가
    못 잡는 끊긴 참조)는 모두 그날 실제로 관측된 결함이다. 특히 §5는 린터를 8/8
    통과시킨 뒤에도 남아 있었다.