코드베이스 아키텍처 개선하기
AI가 코드베이스를 탐색하듯 분석하여 아키텍처 마찰을 발견하고, 테스트 용이성을 개선할 기회를 찾으며, 모듈을 깊게 리팩토링하는 GitHub Issue RFC를 제안합니다.
깊은 모듈(John Ousterhout, "A Philosophy of Software Design")은 작은 인터페이스 뒤에 큰 구현을 숨깁니다. 깊은 모듈은 더 테스트하기 쉽고, AI가 탐색하기 쉬우며, 경계에서 테스트할 수 있게 해줍니다.
프로세스
1. 코드베이스 탐색
subagent_type=Explore를 사용하여 에이전트 도구로 자연스럽게 코드베이스를 탐색하세요. 엄격한 휴리스틱을 따르지 말고 유기적으로 탐색하며 마찰이 느껴지는 지점을 기록하세요:
- 한 가지 개념을 이해하기 위해 여러 개의 작은 파일 사이를 왔다 갔다 해야 하는 곳은 어디인가요?
- 인터페이스가 구현만큼 복잡해서 모듈이 너무 얕은 곳은 어디인가요?
- 테스트 가능성만을 위해 순수 함수가 추출되었지만, 실제 버그는 함수 호출 방식에 숨어 있는 곳은 어디인가요?
- 강하게 결합된 모듈이 그 경계에서 통합 위험을 만드는 곳은 어디인가요?
- 코드베이스 중 테스트되지 않았거나 테스트하기 어려운 부분은 어디인가요?
여러분이 경험하는 마찰이 바로 신호입니다.
2. 후보 제시
깊게 만들 기회의 번호가 매겨진 목록을 제시하세요. 각 후보에 대해 다음 정보를 보여주세요:
- 클러스터: 관련된 모듈/개념
- 결합 이유: 공유된 타입, 호출 패턴, 개념의 공동 소유
- 의존성 카테고리: 네 가지 카테고리는 REFERENCE.md를 참조하세요.
- 테스트 영향: 경계 테스트로 대체될 기존 테스트들
아직 인터페이스를 제안하지 마세요. 사용자에게 물어보세요: "이 중에서 어떤 것을 탐색하시겠습니까?"
3. 사용자가 후보 선택
4. 문제 공간 프레임
하위 에이전트를 생성하기 전에, 선택된 후보에 대한 문제 공간을 사용자에게 설명하세요:
- 새로운 인터페이스가 만족해야 하는 제약 조건들
- 의존해야 하는 종속성들
- 제약 조건을 구체적으로 보여주는 대략적인 예시 코드 스케치 - 제안이 아니라 제약 조건을 구체화하는 수단입니다.
이 내용을 사용자에게 보여준 후 즉시 5단계로 진행하세요. 사용자는 문제를 읽고 생각하는 동안 하위 에이전트가 병렬로 작업합니다.
5. 여러 인터페이스 설계
에이전트 도구를 사용하여 3개 이상의 하위 에이전트를 병렬로 생성하세요. 각 에이전트는 깊어진 모듈에 대해 근본적으로 다른 인터페이스를 생성해야 합니다.
각 하위 에이전트에 별도의 기술 브리핑(파일 경로, 결합 세부 사항, 의존성 카테고리, 숨겨지는 내용)을 프롬프트로 제공하세요. 이 브리핑은 4단계의 사용자 대상 설명과 독립적입니다. 각 에이전트에 다른 설계 제약을 부여하세요:
- 에이전트 1: "인터페이스를 최소화하세요 - 최대 1-3개의 진입점을 목표로 하세요"
- 에이전트 2: "유연성을 극대화하세요 - 많은 사용 사례와 확장을 지원하세요"
- 에이전트 3: "가장 일반적인 호출자에 최적화하세요 - 기본 사례를 간단하게 만드세요"
- 에이전트 4(해당되는 경우): "경계 간 의존성을 위해 포트 및 어댑터 패턴으로 설계하세요"
각 하위 에이전트는 다음을 출력합니다:
- 인터페이스 시그니처(타입, 메서드, 매개변수)
- 호출자가 어떻게 사용하는지 보여주는 사용 예시
- 내부적으로 숨기는 복잡성
- 의존성 전략(의존성 처리 방식 - REFERENCE.md 참조)
- 트레이드오프
설계를 순차적으로 제시한 후 산문으로 비교하세요.
비교 후에는 자신의 추천을 제시하세요: 어떤 설계가 가장 강력하고 그 이유는 무엇인지. 서로 다른 설계의 요소가 잘 결합될 수 있다면 하이브리드를 제안하세요. 의견을 분명히 하세요 - 사용자는 단순한 메뉴가 아닌 강력한 의견을 원합니다.
6. 사용자가 인터페이스 선택(또는 추천 수락)
7. GitHub Issue 생성
gh issue create를 사용하여 리팩토링 RFC를 GitHub Issue로 생성하세요. REFERENCE.md의 템플릿을 사용하세요. 생성 전에 사용자에게 검토를 요청하지 말고 그냥 생성하고 URL을 공유하세요.