하네스 레포 — 등록 · 가져오기 · 정리

하네스 = CLAUDE.md + 스킬 + 훅. 세 가지를 묶어 부르는 말이다.
"원격에 반영/업데이트" 는 언제나 이 레포를 뜻한다.

<harness_repo>          하네스 정본.  범용으로 일반화된 것만 들어간다
  claude/               CLAUDE.md 조각
  skills/_core/         워크플로우를 고르면 항상 함께 오는 스킬
  skills/<workflow>/    그 워크플로우 전용 스킬
  skills/<pack>/        그 팩 전용 스킬
  shared/               여러 스킬이 함께 쓰는 공용 레이어
  hooks/                훅 설정
  tools/                레포에서 쓰는 검사기
  workflows/*.json      워크플로우 매니페스트
  packs/*.json          팩 매니페스트
  .github/workflows/    CI

고르는 축은 둘이다.

워크플로우   일하는 방식.  고르면 _core 가 함께 온다
팩           주제별 묶음.  자기 스킬만 온다. 여러 개를 함께 골라도 된다

🔴 스킬을 넣었으면 매니페스트에도 넣는다. 안 넣으면 설치기가 나르지 않아
설치처에는 그냥 없다. 포터빌리티 린터는 통과하므로 아무도 못 잡는다 —
그래서 CI 에 매니페스트 정합성 검사를 따로 둔다(tools/check_manifests.py).

🔴 설치기는 둘이 짝이다. install.ps1 과 install.sh 중 한쪽만 고치면
OS 마다 동작이 갈라진다. 실제로 --force 동작이 갈라져 두 번째 실행부터
전 항목이 실패한 적이 있고, 그것을 잡은 것은 CI 가 아니라 사람이었다.

🔴 설치는 복사다 — 링크를 걸지 마라

예전에는 설치처와 레포를 정션으로 묶었다. 그러면 프로젝트에서 스킬을 고치는 순간
레포 원본이 바뀐다. 결과는 셋이다.

다른 프로젝트 오염   그 스킬을 쓰는 모든 프로젝트가 이 프로젝트의 사건 기록을 읽는다
공개 유출           레포가 공개면 고치는 즉시 올라갈 준비가 된다
절차 무력화         "올릴 때 일반화한다" 가 성립하지 않는다 — 일반화 전 상태가 없다

설치는 한 방향이다: 레포 → 설치처. 반대 방향은 아래 등록 절차를 거친다.
설치 스크립트가 링크를 만들고 있으면 그것부터 고친다.

⚠️ 복사의 대가: 갱신이 저절로 오지 않는다. 링크였을 때는 레포가 바뀌면 설치처도
바뀌었다(그게 문제였지만). 복사에서는 누가 가져오지 않으면 영영 옛 것을 쓴다.
그래서 아래 가져오기 절차가 등록 절차와 짝을 이룬다. 한쪽만 있으면 갈라진다.

🔴 설치처가 어디인지 먼저 확인한다

설치처는 한 곳이 아니다. 절차를 시작하기 전에 이 환경이 어느 쪽인지 확인한다.
잘못 잡으면 엉뚱한 사본을 읽고 판단하게 된다 — 대조도 반영도 전부 헛돈다.

	설치처	마커
프로젝트 설치 (권장)	<project>/.claude/skills 한 곳	<project>/.claude/skills/.agent-harness-active
전역 설치	~/.claude/skills · ~/.agents/skills 두 곳	~/.agents/skills/.agent-harness-active

# 이 프로젝트에 깔려 있는가
<harness_repo>/install.sh --project . --status
# 전역에 깔려 있는가
<harness_repo>/install.sh --status

🔴 전역 설치처는 두 곳이다. 반영할 때 한 곳만 고치면 에이전트가 어느 쪽을 읽느냐에
따라 결과가 갈린다. 둘 다 같은 상태로 만든다.

🔴 프로젝트와 전역에 같은 스킬이 둘 다 있으면 서로 다른 사본이 둘이다. 등록할 때는
어느 쪽에서 가져왔는지 밝힌다. 프로젝트 사본에는 그 프로젝트 전용 내용이 섞여 있을
가능성이 전역 사본보다 높다 — 일반화(3단계)를 더 세게 해야 한다.

🔴 여기 올리지 않는 것

무엇	어디로
context-DB	자체 레포에서 관리한다. 두 곳에 두면 갈라진다
실명·소속·학번·사번	가명으로 바꾼다
회사명·부서명·사내 시스템 이름	일반 명사로 바꾼다
서버 IP·호스트명·계정	전부 뺀다
사내 대화·회의 발언 원문	교훈만 남기고 원문은 뺀다
절대 경로	대명사로 바꾼다 (아래)

등록 절차

멈추지 말고 끝까지 간다. 판단이 필요하면 객관식으로 올려 고르게 한다.

0. 레포를 최신으로 맞춘다

git -C <harness_repo> pull --ff-only

🔴 이걸 건너뛰면 4단계의 "같은 이름이 있는지" 판단이 낡은 상태에서 이뤄진다.
다른 PC·다른 세션에서 올린 것을 못 보고 덮어쓰거나, push 단계에서 막힌다.
--ff-only 가 거부하면 갈라진 것이므로 먼저 어긋난 곳을 확인하고 진행한다.

1. 범용과 전용을 가른다

판단 기준은 "다른 프로젝트에서도 쓸 수 있는가" 하나다.
민감한 용어·중요 정보·경로가 들어 있어도 범용이면 범용이다 — 그건 3단계에서 지운다.
내용이 아니라 쓸모로 가른다.

가른 결과와 발견한 민감 정보를 사용자에게 보고하고, 답을 기다리지 말고 이어서 진행한다.

2. 딸린 것을 모은다

범용으로 고른 스킬이 혼자 도는 경우는 드물다. 함께 묶는다.

• 그 스킬이 부르는 훅
• 그 스킬이 전제하는 CLAUDE.md 조각
• 스크립트·스키마·템플릿

3. 일반화한다

대상	바꾸는 법
사람 이름	가명 — 홍길동, 김철수
경로	대명사 — <path_information>, <project_root>, <harness_repo>
조직·시스템 이름	일반 명사

🔴 이미 올라가 있는 것도 본다. 예전에 올린 것에 실명이나 절대 경로가 남아 있으면
이번에 함께 고친다.

여기 없는 종류의 민감 정보를 만나면 사용자와 논의한 뒤 이 표에 추가한다.

4. 같은 이름이 있는지 본다

있으면 레포 쪽 내용을 먼저 읽는다. 레포에만 있는 내용이 있으면 병합을 검토한다.

합당하면          알아서 병합한다
큰 변경이 필요하면  사용자와 논의한 뒤 진행한다
유사한 스킬을 합치려면  사용자와 논의한 뒤 진행한다

5. 릴리즈에 적는다

무엇이 왜 바뀌었는지 남긴다. 다음에 볼 사람은 이 기록만 본다.

6. push 하고 보고한다

반영하려던 하네스 목록과 성공 여부
미반영 목록과 그 이유
특이사항

가져오기 절차

레포에 새 내용이 생겼을 때 이 환경에 맞게 받아 온다.
멈추지 말고 끝까지 간다. 판단이 필요하면 객관식으로 올려 고르게 한다.

1. 레포를 최신으로 맞추고 무엇이 왔는지 본다

git -C <harness_repo> pull --ff-only
git -C <harness_repo> log --oneline <이전_커밋>..HEAD

커밋 로그와 릴리즈 노트를 먼저 읽는다. 파일 목록만 보면 왜 바뀌었는지 모른다.

2. 레포와 설치처를 대조해 셋으로 가른다

대조하기 전에 설치처부터 정한다(위 "설치처가 어디인지 먼저 확인한다").
프로젝트 설치면 그 폴더 한 곳, 전역이면 두 곳 모두가 대조 대상이다.

새것      레포에만 있다              → 이 환경에 필요한지 판단한다(3단계)
다름      양쪽에 있는데 내용이 다르다  → 병합 대상(4단계)
로컬 전용  설치처에만 있다             → 아직 등록하지 않은 것이거나 이 환경 전용

손으로 세지 마라 — 설치기가 세어 준다. 설치를 그대로 한 번 돌리면, 이미 있는
것은 건너뛰면서 내용이 실제로 다른지까지 대조해 따로 모아 준다.

복사 0개, 8개 건너뜀(같음 6 · 변경됨 2), 0개 실패

🔴 병합이 필요합니다 — 설치처 내용이 레포와 다릅니다:
  - <skill>   내용 다름 1  (SKILL.md)

여기 뜬 것이 곧 다름 목록이다. 뜨지 않은 것은 볼 필요가 없다.
__pycache__ · *.pyc · *.bak_* · 기록/ 은 비교에서 빠지므로 오탐이 없다.
훅·CLAUDE.md 조각은 설치기가 나르지 않으므로 그 둘만 손으로 본다.

3. 새것은 세부를 읽고 필요한 것만 고른다

🔴 전부 가져오지 않는다. 이 환경에 없는 도구를 전제하거나, 다른 워크플로우 전용이거나,
여기서 쓰지 않는 절차를 담은 스킬이 섞여 있다.

각 스킬의 description 과 본문을 읽고 판단한다.

가져온다     이 환경의 도구·워크플로우와 맞고, 여기서 할 일에 쓰인다
안 가져온다   전제하는 도구가 없다 / 다른 워크플로우 전용 / 여기서 안 쓰는 절차
보류        판단이 갈리면 사용자에게 객관식으로 올린다

4. 다른 것은 병합한다 — 이 환경의 구체값을 지킨다

🔴 레포는 일반화돼 있고 설치처는 구체화돼 있다. 그냥 덮어쓰면 이 환경에 맞춰 둔 값이
사라진다.

레포에서 가져올 것    새 절차 · 새 규칙 · 고쳐진 설명 · 이력
설치처에서 지킬 것    실제 경로 · 실제 이름 · 이 환경 전용으로 덧붙인 절 · 로컬 이력

양쪽이 같은 자리를 서로 다르게 고쳤으면 그것만 뽑아 사용자에게 올린다.

5. 표로 보고한다

하네스	상태	판단	근거
이름	새것 / 다름 / 로컬 전용	가져옴 · 병합 · 건너뜀	한 줄

6. 반영하고 결과를 보고한다

승인받은 것만 설치처에 반영한 뒤 낸다.

가져온 목록과 성공 여부
안 가져온 목록과 그 이유
병합에서 손댄 곳 — 무엇을 지키고 무엇을 덮었는지
특이사항

⚠️ 이 절차는 레포를 고치지 않는다. 가져오다 레포 쪽 문제를 발견하면 기록해 두고,
고치는 것은 등록 절차로 따로 한다. 두 방향을 한 번에 섞으면 무엇이 원본인지 흐려진다.

정리 절차

멈추지 말고 끝까지 간다. 판단이 필요하면 객관식으로 올려 고르게 한다.

0. 레포를 최신으로 맞춘다

git -C <harness_repo> pull --ff-only

등록 절차와 같은 이유다. 낡은 상태에서 합치면 남이 올린 것을 지운다.

1. 비슷한 것을 모은다

각 하네스의 description 을 읽고 비슷한 것끼리 묶는다.

2. 표로 보고한다

묶인 것끼리 본문을 읽어 용도를 가른 뒤 표로 낸다.

하네스	목적과 역할	유사도	개선 계획
이름	무엇을 하는 것인지	1~100	한 줄

상세는 사용자가 물은 것만 뒤에 붙인다. 묻지 않은 것을 길게 쓰지 않는다.

3. 승인받은 것만 병합한다

표를 보고 사용자가 고른 것만 손댄다.

4. 릴리즈에 적는다

5. push 한다

6. 🔴 설치처에 반영한다

정리는 여기서 끝나지 않는다. 레포에서 A·B 를 C 로 합쳤으면 설치처에는 아직 A 와 B 가
그대로 있다. 합친 결과를 가져오고 낡은 것을 걷어내지 않으면, 에이전트가 사라진 스킬을
계속 읽는다.

가져오기 절차 2·6 단계로 반영한 뒤 보고한다.

반영한 목록과 성공 여부
미반영 목록과 그 이유
설치처에서 걷어낸 옛 스킬
특이사항

이력 (필수 기록)

• 생성일: 2026-09-17
• 업데이트 횟수: 2
• 최근 업데이트: 2026-09-22 (설치처가 둘 중 하나임을 절차 앞에 못박음 — 프로젝트 설치 도입)
• 사용 이력
  • 2026-09-22 — 설치기에 -Project / --project 가 생겼다. 그전까지 이 스킬은
    설치처를 전역 두 곳으로 단정하고 있었다. 프로젝트 설치가 생기면서 대조 대상이
    환경마다 달라져, 절차 앞에 설치처 확인 단계를 세웠다. 잘못 잡으면 엉뚱한 사본을
    읽고 판단하므로 대조도 반영도 전부 헛돈다. 함께 적어 둔 것: 프로젝트 사본은 전용
    내용이 섞여 있을 확률이 높아 등록 시 일반화를 더 세게 해야 한다.
  • 2026-09-17 — 가져오기 절차를 넣었다. 등록만 있고 받아 오는 쪽이 없었다.
    링크였을 때는 레포가 바뀌면 설치처도 바뀌었지만(그게 문제였다), 복사로 바꾼 뒤로는
    누가 가져오지 않으면 영영 옛 것을 쓴다. 두 절차가 짝을 이뤄야 갈라지지 않는다.
    함께 메운 누락 둘: ① 등록·정리 모두 시작할 때 pull 이 없어 낡은 상태에서
    판단하고 있었다 ② 정리가 push 로 끝나 설치처에 옛 스킬이 남는 문제가 있었다.
  • 2026-09-17 — 신설. 설치처와 레포를 묶고 있던 정션 34개를 끊고 복사 방식으로 바꾼 날
    함께 만들었다. 정션이 있으면 3단계(일반화)가 원리적으로 불가능하다는 것이
    이 스킬을 만든 이유다 — 고치는 순간 원본이 이미 바뀌어 있으니 일반화 전 상태가 없다.