Repository navigation
[Chore] 하네스 구성요소 개명·분리 — core/tripfit 구분 #128
Description
priority 미지정 —
harness-milestone.md⛔에 따라 에이전트가 스스로 must/could를 판단하지 않았습니다. 사용자 확인 후 라벨을 붙입니다.
한 줄 요약
하네스 규칙·스킬·훅·에이전트의 이름을 역할이 드러나게 바꾸고, 한 파일이 여러 관심사를 담고 있던 3곳을 쪼갠다.
목표
파일명만 보고 그 구성요소가 무슨 일을 하는지 알 수 있게 된다. 이름에 core-(프로젝트 무관)와 tripfit-(프로젝트 고유) 구분이 생겨, 하네스를 다른 저장소로 복제할 때 무엇을 가져가고 무엇을 남길지가 파일명으로 자명해진다.
배경
- 사용자가 이 하네스를 다른 프로젝트에서도 쓰려고 별도 저장소로 복제할 계획이다(2026-09-04 결정). 이번 이슈는 복제 전에 TripFit 안에서 이름·구조를 먼저 정리하는 단계다.
- 현재 이름의 문제는 셋이다 — 동어반복(
debug-bug,defer-followup), 내부 은어(harness-*접두사), 길이(senior-spring-backend-reviewer29자). - 이름만이 아니라 한 파일이 여러 일을 하는 것도 문제다.
harness-workflow.md는 195줄/20.9KB로 always-load 규칙 중 최대이며 "하지 말 것"(⛔ STOP 6개)과 "어떤 순서로 할 것"(3트랙×4게이트)이 한 파일에 있다.harness-milestone.md는 일반 원칙과 TripFit 고유 사실(Release Gate·용어표·이슈번호)이 섞여 있다. - 파급 범위 실측 —
harness-workflow127회/63개 파일,spring-boot-java93회/43개..claude/·docs/밖으로도AGENTS.md·CLAUDE.md·.github/CONTRIBUTING.md·deploy/environment-reference.md·scripts/notify-api-breaking-change.sh·.claude/settings.json이 이름을 참조한다.
관련
- 스펙:
docs/specs/cross-cutting/harness-component-rename.md - 선행 개편: [Chore] 하네스 재구성 — 3 트랙 × 4 게이트 #127 (3 트랙 × 4 게이트 재구성) — 이번 작업은 그 구조를 유지한 채 이름·파일 경계만 정리한다
완료 조건
- 규칙 5개 개명 —
harness-workflow→core-guardrails+core-workflow,harness-milestone→core-scope+tripfit-release,harness-follow-up→core-followup,workflow-tools→core-tools,plain-language-reporting→core-reporting - 스킬 4개 개명 —
verify→preflight,refactor-audit→safe-refactor,defer-followup→defer,debug-bug→debug - 훅 3개 개명 (
deny-/auto-접두사) +.claude/settings.json경로 갱신 - 에이전트 1개 개명 —
senior-spring-backend-reviewer→spring-reviewer - 참조 동기화 9곳 —
.claude/rules/README.md(다이어그램+표 6개),settings.json,AGENTS.md,CLAUDE.md,docs/harness-engineering.md,docs/harness/layer1~3+architecture-diagrams.md,.github/CONTRIBUTING.md,deploy/environment-reference.md,scripts/notify-api-breaking-change.sh,docs/specs/README.md -
src/**/*.javadiff 0줄 —verify가 Java 60여 파일에 "검증하다"라는 일반 단어로 존재해 오탐 위험이 있다 - 문서 내 상대 링크 중 깨진 것 없음
-
./gradlew test통과
범위 밖
- 플러그인화 —
plugin.json·marketplace.json작성. 할지 여부 자체가 미결정 (플러그인은rules/미지원 확인됨) - 별도 저장소로 복제 — 이번 작업 다음 단계
- 어댑터(
harness-map.md) 도입 ·docs/경로를 역할 이름으로 치환 - STOP 절·게이트 내용 변경 — 이번은 이동·개명만, 정책은 불변
specify·retro·researcher·doc-reviewer·warn-breaking-change개명 — 개명 사유에 해당하지 않음specify→spec은 하지 않는다 —docs/specs/참조가 228회라 개명 후 "spec 스킬"·"docs/specs"·"스펙"이 비슷하게 읽혀 직관성이 오히려 떨어진다- path-scoped 규칙 7개 개명 — 이미 적용 시점이 이름에 드러남
비고
분리 후 always-load 규칙은 5개 → 7개가 되지만, 내용 이동이라 토큰 총량은 거의 그대로다. 가독성을 위한 의도된 트레이드오프.
Activity
chhezue commentedon Sep 4, 2026
범위 추가 — always-load 다이어트 (F)
tripfit-release.md가 매 세션 자동 로드되는데 절반 가까이가 "과거에 뭐가 폐지됐다"는 기록이라, 이력 2건을docs/product/release-milestones.md로 옮겼다.[미정]전용 트래커(#2) 폐지 이력 → 부록에 신규 추가 (거기 없던 내용). 운영 규칙은core-scope.md로 흡수옮기지 않은 것과 그 이유
glossary.md에C1 윈도우정의가 없어 이관하면 유실된다. 또glossary.md는 규칙이 아니라 자동 로드되지 않아, trip·schedule 작업 중 에이전트가 정의를 모른 채 코딩할 위험이 생긴다paths:로 대체할 수 없다측정: always-load 25,635자 → 25,467자, 0.7% 감소. 사전 추정 5%에 한참 못 미쳤다 — 이관하면서 남은 절에 안내 문장을 새로 써야 했기 때문이다. 토큰 절감은 이 작업의 근거가 못 되고, 실익은 규칙 파일 가독성과 하네스 이식 편의 두 가지다.
chhezue commentedon Sep 4, 2026
범위 추가 — 폐지된 릴리즈 축 용어 전면 제거 (G)
2026-08-26에 폐지된 구 도메인 축 용어가 저장소 전체에 남아 있어 전부 걷어냈다. 폐지 사실을 반복 설명하는 문장이 규칙·스펙·스크립트에 흩어져 있어, 읽을 때마다 "이건 지금 쓰는 건가"를 판단해야 했다.
scripts/github-bootstrap.sh— 구 라벨 4개·구 마일스톤 8줄 제거. GitHub에서 라벨은 이미 삭제·마일스톤은 전부 Close라 실행이 끝난 dead code였다 (STOP §4).bash -n통과docs/audits/doc-writing-audit.md파일 삭제 — 감사 대상이 "잔존 488회"였고 문서 스스로 "전부 해소됐다"고 기록한 완료된 감사. 인바운드 참조 3곳도 정리docs/product/release-milestones.md— §0의 긴 폐지 서사와 변경 이력 표를 "축은 3개 질문뿐" 표로 압축, 폐지 내역은 부록 목록으로만. 26회 → 0회결과: 저장소 전체 3건 잔존. 이번 개명 스펙 본문 2건과, 지금은 없어진 Java 주석을 인용한 감사 문장 1건(고치면 인용이 거짓이 되므로 유지)뿐이다.
src/**/*.java에는 원래 한 건도 없었다.chhezue commentedon Sep 5, 2026
PR #129 생성 완료 — 완료 조건 8개 모두 코드·문서로 확인 후 체크:
scripts/notify-api-breaking-change.sh는 애초에 옛 이름을 참조하지 않아 수정 불필요, 대신scripts/github-bootstrap.sh등 포함)src/**/*.javadiff 0줄 확인./gradlew testBUILD SUCCESSFULCloses 예정: #129 merge 시 자동 close.
Merge pull request #129 from Central-MakeUs/chore/128-harness-compone…