tt-a1i/simplify-codebase

코드베이스 단순화 – 안전한 코드베이스 정리용 AI 에이전트 스킬

무엇인가요

• AI 코드 에이전트(예: Codex, OpenAI 기반 봇)용 스킬(플러그인)으로, 기존 리포지토리를 감사하고, 코드를 안전하게 제거할 수 있음을 증명한 후, 적용하면서 전체 증거 기록을 유지합니다.
• 일반적인 린터나 불필요 코드 제거 도구가 아닙니다. 오래된 API, 고립된 상태, 중복된 추상화, 호환성 쉴드와 같은 의도하지 않은 복잡성에 초점을 맞추며, 유지보수 비용이 이익을 상회할 때만 삭제합니다.

작동 방식

모드	범위	기능
조사(읽기 전용)	집중적 – 단일 서브시스템 또는 광범위 – 전체 리포지토리	파일, 런타임 등록, 데이터 형식, 외부 소비자 스캔 후, 증거 기록이 첨부된 "단순화 후보"의 순위 목록 생성
변경(승인된 편집)	동일한 범위	후보가 안전함이 입증된 후 삭제 수행, 최소 검증 세트 실행, 롤백 계획 출력

각 후보는 다음을 포함하는 증거 기록을 동반합니다:

• 소유 경계, 파일 및 줄 번호
• 도입하는 유지보수 부담
• 누구(테스트, 런타임, 외부 서비스)가 소비하는지
• 정확한 삭제 경계(공유 파일 멤버 포함)
• 소실되는 호환성 또는 관찰 가능한 동작
• 잘못된 삭제를 포착할 수 있는 최소 테스트
• 이동 비용 대비 순 복잡성 감소량

핵심 보호 조치

• 공개 API, 플러그인 등록, 데이터 마이그레이션 경로, 동시성 프리미티브, 또는 여전히 검증된 소비자가 있는 모든 아티팩트에는 절대 손대지 않습니다.
• 실제 소비자가 식별되지 않으면, 추측 대신 코드 유지를 권장합니다.

설치

# Codex 호환 에이전트에 추천
git clone https://github.com/tt-a1i/simplify-codebase.git ~/.codex/skills/simplify-codebase

• SKILL.md 메타데이터를 존중하는 모든 에이전트 플랫폼에서 로드 가능.
• 경량 HTML 렌더러(노드 ≥ 18, 추가 npm 패키지 없음)를 포함하여 선택적 시각화 보고서 제공.

일반적인 사용 패턴

# 1️⃣ 전체 리포지토리 감사, 변경 없음
$simplify-codebase audit --scope broad --dry-run

# 2️⃣ 특정 플래그나 상태 조사
$simplify-codebase survey --focus readiness-flags

# 3️⃣ 검증된 단순화 적용
$simplify-codebase change --candidate 42 --apply

# 4️⃣ PR에서 결과 통합
$simplify-codebase integrate --pr 123

# 5️⃣ 인터랙티브 클리닝 맵(HTML) 생성
$simplify-codebase report --visual

• 명령어는 기본적으로 텍스트 증거 보고서를 반환합니다. --visual를 추가하면 검증된 구성 요소와 그 관계를 보여주는 자체 포함형 HTML 지도를 생성합니다.

출력물

• 조사 보고서 – 커버리지 설명, 순위별 증거 기록, 반례, 미해결 질문, 다음에 필요한 증거
• 변경 보고서 – 실제 파일 차이, 계층적 검증 결과, 잔여 리스크 평가, 작업 수령 증명, 되돌릴 수 있는 "취소" 스크립트
• 옵션 시각화 보고서 – 내장된 Archify 렌더러로 구축된 인터랙티브 데스크톱 친화형 HTML 페이지. 검증된 결과만 표시하며, 추측된 런타임 영향은 절대 표시하지 않습니다.

성숙도

• 973개 파일의 혼합 Python/TypeScript 프로젝트에서 변경, 광범위, 통합, 결정 기록 시나리오를 포함해 검증됨.
• 테스트 스위트와 계약 파일은 visualization/test/ 및 docs/validation.md에 위치.

기여 방법

• 문제 및 PR을 환영합니다. 특히 놓친 소비자, 오진 삭제, 검증 흐름의 공백을 드러내는 경우.

라이선스

• MIT (see LICENSE).

---

Simplify Codebase는 대규모 레거시 코드베이스에 형식적이고 증거 기반의 정리 기능을 제공하는 전문적인 AI 에이전트 확장으로, 팀이 숨겨진 오류 위험 없이 장기적인 유지보수 부담을 줄일 수 있도록 지원합니다.