deprecation-guide
시스템·모듈·API 폐기와 소비자 이관 가이드 — 폐기 결정 5질문, 권고형/강제형 구분, 대체 구축→공지→점진 이관→사용량 0 확인 후 제거, Strangler·Adapter·Feature Flag 패턴, 좀비 코드 신호. Deprecation and migration guide: decision questions, advisory vs compulsory, replace-announce-migrate-remove process, Strangler/Adapter/Feature-Flag patterns, zombie-code signals. Use when: "폐기", "레거시 제거", "마이그레이션 계획", "좀비 코드", "API 버전 전환", deprecating a system or API, removing dead code.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-29
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- deprecation-guide
- description
- 시스템·모듈·API 폐기와 소비자 이관 가이드 — 폐기 결정 5질문, 권고형/강제형 구분, 대체 구축→공지→점진 이관→사용량 0 확인 후 제거, Strangler·Adapter·Feature Flag 패턴, 좀비 코드 신호. Deprecation and migration guide: decision questions, advisory vs compulsory, replace-announce-migrate-remove process, Strangler/Adapter/Feature-Flag patterns, zombie-code signals. Use when: "폐기", "레거시 제거", "마이그레이션 계획", "좀비 코드", "API 버전 전환", deprecating a system or API, removing dead code.
03 SKILL.md 正文
Deprecation & Migration Guide
핵심 전제: Hyrum's Law — 사용자가 충분히 많으면 API 의 모든 관찰 가능한 동작(버그·타이밍 포함)에 누군가 의존한다. 공지만으로는 이관되지 않으므로 능동적 이관과 사용량 측정이 필요하다.
1. 결정
| # | 질문 | 판단 |
|---|---|---|
| 1 | 아직 고유한 가치가 있는가? | 대체 불가 기능이 있으면 보류 |
| 2 | 소비자는 몇인가? | 호출처·트래픽으로 정량화 |
| 3 | 대체가 존재하는가? | 없으면 먼저 구축 |
| 4 | 소비자별 이관 비용은? | 자동화 가능하면 소유자가 수행 |
| 5 | 유지 비용은? | 보안·운영 시간·복잡성 |
- Advisory: 이관 선택적, 구 시스템 안정 — 경고 로그·문서
- Compulsory: 보안·차단 이슈 — 확정 기한 + 이관 도구/가이드 제공 필수
- Churn Rule: 인프라/라이브러리 소유자가 이관 책임을 진다(또는 하위 호환을 제공)
2. 프로세스
- 대체 구축 — 핵심 유스케이스 커버, 프로덕션 검증
- 공지 — 상태·대체·제거 예정일·이유·이관 가이드·담당자. 코드에는 언어별 deprecation 표시
(Kotlin
@Deprecated(replaceWith = ReplaceWith(...)), Go// Deprecated:주석 단락 —staticcheckSA1019 가 사용처를 경고) - 점진 이관 — 소비자별: 접점 식별 → 교체 → 테스트 → 구 참조 제거
- 제거 — 사용량 0 을 메트릭/로그로 확인 → 코드·테스트·문서·설정 삭제 → 스키마 정리는 expand-contract 의 contract 단계로
3. 패턴
| 패턴 | 방식 | 적합 |
|---|---|---|
| Strangler | 신구 병렬, 트래픽 0→100% 이동 | 대규모 교체, API 버전 전환 |
| Adapter | 구 인터페이스 유지, 내부만 신구현 위임 | 소비자가 많아 인터페이스 즉시 변경 불가 |
| Feature Flag | 소비자/요청별 분기 | 점진 전환, 비교, 빠른 롤백 |
4. 좀비 코드 신호
6개월+ 무커밋인데 소비자 존재 / 소유자 없음 / 방치된 실패 테스트 / CVE 방치 의존성 / 사라진 시스템을 가리키는 문서. 발견 시: 소유자 확인 → 폐기 여부 결정 → 위 프로세스.
Red Flags
대체 없는 폐기 공지, 이관 도구 없는 기한, 수년째 진전 없는 소프트 폐기, 폐기된 시스템에 새 기능, 사용량 측정 없이 삭제.
Related
workflow:shipping-guide— 대체 시스템의 플래그·롤아웃observe:observe-report— 하네스 자산(스킬·커맨드)의 미사용 후보 탐지
04 同仓库更多 Skills
sync-claude-md
커밋·푸시·PR/MR 직전에 이번 변경이 프로젝트 CLAUDE.md 를 낡게 만드는지 검토하고, 필요할 때만 갱신 diff 를 제안한다 — 아키텍처·디렉터리 구조, 새 통합/MCP, 컨벤션, 빌드·CI·도구, 주요 의존성 변화가 대상. 해당 없으면 한 줄로 끝낸다. Reviews whether pending changes make the project CLAUDE.md stale (architecture, integrations, conventions, build/CI/tooling, major dependencies) and proposes a minimal update diff only when needed. Use when: "CLAUDE.md 갱신 필요해?", "CLAUDE.md 동기화", 커밋/푸시/MR 전에 구조·도구가 바뀐 변경을 정리할 때, sync CLAUDE.md, check CLAUDE.md before commit or PR.
spec-driven-dev
새 기능·프로젝트·큰 변경을 코드보다 스펙 먼저로 진행하는 게이트 워크플로(SPECIFY → PLAN → TASKS → IMPLEMENT) — 가정 명시, 측정 가능한 성공 기준, Always/Ask/Never 경계, 단계별 사람 검토로 범위 이탈과 재작업을 줄인다. Spec-before-code gated workflow for new features or significant changes: explicit assumptions, measurable success criteria, boundaries, and a human review between stages. Use when: "스펙 먼저", "기능 명세", "요구사항 정리", starting a new feature or project, a significant change with vague requirements. 단순 버그 수정·1~2줄 변경엔 불필요.
shipping-guide
프로덕션 배포 전후 가이드 — 배포 전 체크리스트, 피처 플래그 수명주기, 단계적 롤아웃과 진행/보류/롤백 임계값, 롤백 계획 템플릿, 배포 후 모니터링. Production shipping guide: pre-launch checklist, feature-flag lifecycle, staged rollout with go/hold/rollback thresholds, rollback plan template, post-launch monitoring. Use when: "배포 준비", "릴리즈 전 점검", "롤아웃 계획", "롤백 계획", preparing a production deploy, staged rollout, feature flags.
retro
세션 회고·교훈 컴파운딩 — 이번 세션의 교정·실수·발견을 추출해 품질 기준(재현·일반화·판정 가능성)으로 거르고, 컨벤션 변화는 sync-claude-md 위임, 반복 실수는 tasks/lessons.md(#가드-훅-후보 태그), 스킬 지식 갱신은 수정 제안으로 나눈다. 모든 적용은 승인 후. Session retrospective that turns corrections, mistakes, and discoveries into vetted lessons routed to CLAUDE.md sync, tasks/lessons.md, or skill-edit proposals, with user approval before any write. Use when: "회고", "레트로", "교훈 정리", "같은 실수 반복", "재발 방지 규칙", retrospective, lessons learned, wrapping up a task, review, or loop. 여러 실행에 걸친 하네스 개선은 harness:evolve.
project-rules
현재 프로젝트의 스택(빌드 파일 버전, 마이그레이션 도구, ORM 유무, ES 사용, git 호스트)을 감지해 프로젝트 루트 AGENTS.md 의 마커 블록(스택 사실 + 항상 적용되는 스페셜리스트 핵심 ≤15줄 — Claude Code·Codex·Antigravity 공통)과 CLAUDE.md 의 `@AGENTS.md` 연결, Claude 전용 경로 한정 .claude/rules/<stack>-specialist.md(해당 버전에 실제로 맞는 상세 함정)를 diff 로 제안하고, 스택 플러그인을 런타임별로 프로젝트 범위에서 켜는 법을 안내한다. 이전 버전 출력(CLAUDE.md 블록·specialist-core.md)은 AGENTS.md 로 이전을 제안. --check 는 버전 불일치·사라진 ID·크기 한도·연결 누락을 점검. Detects the project's stack and proposes a cross-runtime AGENTS.md block (stack facts + always-on specialist core) linked from CLAUDE.md via @AGENTS.md, plus Claude-only path-scoped specialist rules; migrates the older CLAUDE.md-block layout; --check audits drift. Use when: "이 프로젝트 세팅", "프로젝트 규칙 생성", "AGENTS.md/CLAUDE.md 점검", project setup, generate project rules, audit AGENTS.md or CLAUDE.md drift.
post-merge
MR 머지 완료 후 Plane 이슈 종료와 Outline 문서 업데이트를 자동으로 처리하는 오케스트레이터 스킬입니다. issue-tracker와 document-latest 스킬을 연계 실행하여 머지 후 후속 작업을 일괄 처리합니다. Orchestrates post-merge follow-up after an MR is merged: chains the issue-tracker and document-latest skills to close the Plane issue and update Outline wiki docs in a single batch. Use when: an MR was just merged, closing tickets and syncing documentation after a merge, post-merge cleanup.