문서를 만드는 AI 에이전트 앱을 새 스택과 레거시 스택을 헷갈리지 않고 고치기

## 먼저 코드에서 실제 시작 명령과 설정 찾기 패키지 메타데이터, 콘솔 진입점, 구성 로더, 환경 변수 처리, 런타임 작업공간을 만드는 코드부터 살펴본다. 충돌이 발생하면 이러한 실행 가능 영역을 서술형 문서보다 우선한다. - 어떤 명령이 기본 애플리케이션을 시작하는지 확인한다. - 어떤 명령이 레거시 또는 MCP 호환 서비스를 노출하는지 확인한다. - 각 명령을 실제 모듈과 함수까지 추적한다. - 구성 템플릿과 기본 작업공간 동작을 찾는다. - 참조된 모든 경로가 현재 작업 사본에 존재하는지 확인한다. 오래된 개요는 현재 시작 경로의 증거가 아니라 역사적 맥락으로 취급한다. ## 변경을 맡은 쪽이 현재 스택인지 레거시 스택인지 정하기 저장소는 현재 제품 스택과 함께 전용 엔드포인트를 계속 제공하는 이전 세대 라이브러리를 배포할 수 있다. 편집하기 전에 어느 스택이 소유하는지 확인한다. 현재 스택은 다음을 소유할 수 있다. - 명령줄 인터페이스와 초기 설정 흐름 - 오케스트레이션과 다중 에이전트 실행 - 연구, 생성, 디자인 에이전트 - 검색, 성찰, 변환, 작업 관리를 위한 MCP 방식 도구 - 구성, 로깅, 작업공간 유틸리티 - 브라우저 기반 HTML 변환과 Node 보조 도구 - 통합 중심 테스트 레거시 스택은 여전히 템플릿 기반 생성, 레이아웃 추론, 파싱, 평가, 호환성 서버를 소유할 수 있다. 한 스택에서 공유 개념을 변경하면 다른 스택도 갱신된다고 가정하지 않는다. ## 특수한 경우를 줄이고 짧은 함수로 단순하게 설계하기 조건 분기를 계속 쌓지 말고 예외적인 경우를 일반적인 경우로 바꾸는 설계를 우선한다. 가상의 아키텍처 문제가 아니라 저장소의 실제 문제를 해결한다. - 실제 요구 사항을 충족한다면 직접적이고 운영 부담이 적은 해결책을 선택한다. - 함수는 짧고 집중된 형태로 유지하고 명확하게 이름을 붙인다. - 불필요한 복잡성을 결함으로 취급한다. - 들여쓰기 단계가 3단계를 넘으면 코드를 재구성해야 한다는 신호로 본다. - 구체적인 실패 방식도 없이 정상 제어 흐름을 광범위한 예외 래퍼 안에 숨기지 않는다. - 비판은 사람보다 코드, 설계 또는 가정을 대상으로 기술적으로 제시한다. 좋은 판단은 더 적은 특수 사례, 더 작은 범위, 쉽게 검증할 수 있는 동작으로 드러난다. ## 타입 주석을 붙이고 의존성을 최소로 유지하기 유지관리되는 스택 전체에 일관된 규칙을 적용한다. - 함수와 메서드에 타입 주석을 추가한다. - 저장소에서 선언한 언어로 기술 문서와 코드 주석을 작성한다. - 현재 의존성 관리자, 저장소 검색 도구, 언어 기능, 지원되는 라이브러리 API를 사용한다. - 더 이상 권장되지 않는 형식보다 현재 직렬화 및 유효성 검사 인터페이스를 우선한다. - 의존성과 전체 코드 양을 최소화한다. - 루트 패키지 정의는 기본 제품에 집중한다. - 실제로 격리된 하위 프로젝트의 의존성은 해당 로컬 의존성 파일에 둔다. 단지 정돈하기 위해 의존성을 옮기지 않는다. 런타임과 유지관리 경계가 실제로 존재할 때만 분리한다. ## 연결된 부분까지 변경을 따라가며 Python과 Node 양쪽 살피기 변경할 동작을 소유하는 전체 경로를 점검한다. - 명령줄 동작은 명령 정의, 공유 명령 보조 도구, 구성 로딩을 함께 점검한다. - 오케스트레이션은 기본 조정자와 관련 에이전트 구현을 점검한다. - MCP 동작은 소유권이 현재 도구 서버에 있는지 레거시 호환성 서버에 있는지 판단한다. - 내보내기와 변환은 Python 오케스트레이션 측과 Node 변환 측을 모두 점검한다. - 중복된 생성 개념은 작업이 두 스택을 명시적으로 포괄하지 않는 한 소유 스택만 변경한다. 변경 범위를 제한한다. 비슷한 이름이 두 스택에 모두 나타난다는 이유만으로 두 스택을 모두 리팩터링하지 않는다. ## 기존 설정 이름과 작업 공간 위치를 바꾸지 않고 유지하기 기존 구성 키, 환경 변수, 초기 설정 동작, 구성 예시, 작업공간 위치는 런타임 계약을 이룬다. 작업에 마이그레이션이 명시적으로 포함되지 않는 한 그 이름을 보존한다. 브라우저와 컨테이너 의존성은 선택적인 개발 부가 요소가 아니라 변환 경로의 정상적인 런타임 요구 사항일 수 있다. 네이티브 변환 도구, 모델 자격 증명, 브라우저 자동화, 컨테이너 이미지도 어떤 통합 테스트를 실행할 수 있는지 결정할 수 있다. 런타임 경로를 변경할 때는 다음을 따른다. 1. 모든 구성 출처와 기본값을 식별한다. 2. 초기 설정과 예시가 해당 값을 어떻게 채우는지 추적한다. 3. Python 호출자와 외부 변환 보조 도구를 확인한다. 4. 호환성을 보존하거나 명시적인 마이그레이션 경로를 제공한다. ## 오래된 문서를 코드로 확인하고 테스트를 필요한 환경별로 나누기 문서의 주장을 신뢰하기 전에 현재 파일 트리와 실행 가능한 진입점을 기준으로 확인한다. 이전 문서는 제거된 파일이나 오래된 시작 흐름을 언급하면서도 유용한 개념을 설명할 수 있다. 필요 조건에 따라 테스트를 분류한다. - 격리된 로직을 위한 단위 테스트 - 특수 데이터 경로를 위한 파서 테스트 또는 표시된 테스트 - 샌드박스 도구, 브라우저 또는 PDF 변환, 이미지 처리, 외부 유틸리티를 위한 통합 테스트 - 자격 증명이나 네트워크 서비스를 요구하는 모델 기반 테스트 브라우저, 컨테이너 이미지, 네이티브 변환기 또는 모델 자격 증명이 없다는 것은 검증의 한계이지, 무관한 코드가 고장 났다는 증거가 아니다. ## 의미 있는 최소 테스트를 돌리고 돌리지 못한 검사 보고하기 집중된 변경 순서를 사용한다. 1. 어느 스택과 진입점이 해당 동작을 소유하는지 확인한다. 2. 완전성을 갖춘 가장 작은 범위를 편집한다. 3. 의미 있는 최소 테스트 하위 집합을 실행한다. 4. 직접 결합된 Python, Node, 브라우저, 컨테이너 또는 호환성 경로로만 확장한다. 5. 검증을 막은 의존성 또는 환경 요구 사항을 보고한다. 최종 변경 내역에서 다른 스택에 대한 우발적 변경, 이름이 바뀐 구성 계약, 오래된 문서 참조, 무관한 리팩터링, 테스트하지 않은 언어 간 경계를 검토한다. 변경한 내용, 실행해 본 경로, 통과한 검사, 실행할 수 없었던 검사를 보고한다. 필수 런타임 의존성을 사용할 수 없었다면 검증이 완료되었다고 주장하지 않는다.