Codebase Convergence
리포지토리를 재설계하지 않고도 더 쉽게 이해하고 변경할 수 있도록 만듭니다. 추측성 추상화보다는 증거, 작은 인터페이스, 국소적 수정을 선호합니다.
가드레일
- 다단계 변경 전에 범위, 가정, 보호 대상 콘텐츠, 성공 확인 사항을 명시합니다.
- 아키텍처를 판단하기 전에 리포지토리 지침, 도메인 용어집, 관련 ADR을 읽습니다. 리포지토리의 도메인 이름을 사용합니다.
- 요청 사항을 처리하는 파일만 수정합니다. 관련 없는 사용자 변경 사항은 보존하고, 이 작업으로 인해 더 이상 사용되지 않는 임포트, 코드, 문서만 제거합니다.
- 명시적으로 보호된 도메인 텍스트, 제목, 데이터 정의, 사용자 지정 사본은 잠긴 것으로 간주하고 그대로 유지합니다. 상태가 명확하지 않으면 편집하는 대신 결정 패킷에 포함시킵니다.
- 명시적 승인 없이 숫자 값이나 그 표현(구성, 임계값, 잔액, 비율, 한도, 문서화된 값)을 변경하지 않습니다.
- 비즈니스 규칙, 상태 전이, 상호 작용 동작, 공개 인터페이스 또는 시각적 계약을 묵시적으로 변경하지 않습니다. 수정이 직접적으로 암시되고 동작을 보존하는 경우가 아니라면 결정 사항으로 간주합니다.
- 각 사실에 대해 하나의 진실 공급원을 유지합니다. 다른 문서를 단순히 반복하는 문서를 만들지 않습니다.
워크플로
1. 기준선 설정
- 작업 트리를 검사하고 요청된 영역만 식별합니다. 관련 없는 수정 사항을 기록하되 스테이징하거나 변경하지 않습니다.
- 관련 코드 경로, 상태/데이터 소유권, UI 흐름, 테스트, 마크다운 파일을 매핑합니다. 도메인과 결정을 정의하는 문서를 구현 파일보다 먼저 읽습니다.
- 각 발견 사항을 증거(파일, 상충되는 문장이나 경로, 사용자 영향, 직접 해결 가능 여부)와 함께 기록합니다.
- 발견 사항을 분류합니다.
- 직접 수렴: 중복, 오래된 링크, 모순되는 비잠금 산문, 또는 동작을 보존하는 수정이 가능한 국소적 구현/UI 결함.
- 결정 필요: 숫자 값, 규칙, 동작, 보호된 콘텐츠, 공개 인터페이스 또는 모호한 진실 공급원.
- 아키텍처 후보: 잠재적으로 더 깊은 모듈 또는 분할 지점이 아직 합의되지 않은 변경.
2. 중요한 결정은 한 번에 질문
질문하기 전에 발견을 완료합니다. 해결되지 않은 모든 항목을 포함하는 하나의 결정 패킷을 보내십시오. 여러 턴에 걸쳐 질문을 분산하지 마십시오.
각 숫자 항목에 대해 식별자와 파일, 현재 값, 불일치 증거, 영향, 권장 사항을 포함하거나 값을 제안하지 않음을 명확히 밝힙니다. 사용자가 명시적으로 승인할 때까지 영향을 받는 숫자 표현을 편집, 정규화, 이동 또는 제거하지 마십시오.
동일한 패킷에 다른 중요한 불확실성(잠긴 콘텐츠 상태, 동작 선택, 소유권 충돌, 아키텍처 선택)을 포함시킵니다. 승인이 보류되는 동안 독립적인 직접 수렴을 계속합니다.
3. 직접 수렴 적용
각 변경 사항을 발견 사항에 추적 가능하도록 수술적으로 유지합니다.
문서
- 각 문서에 하나의 책임을 부여합니다. 기존 규칙을 존중합니다. 그렇지 않으면 최소 집합(진입점 개요, 아키텍처/시스템 맵, 도메인 또는 제품 규칙, 결정, 현재 작업/상태)을 유지합니다.
- 중복된 PRD, 계획, 작업 로그는 권위 있는 콘텐츠를 한 번만 유지하여 병합합니다. 내구성 있는 근거는 프로젝트의 결정 기록으로 이동하고 운영 상태는 짧게 유지합니다.
- 잠긴 블록을 재배치할 때는 그대로 유지합니다. 병합이 잠긴 블록이나 숫자 표현을 변경하는 경우 해당 부분은 승인을 위해 남겨둡니다.
- 반복, 오래된 참조, 상충되는 비잠금 설명을 제거합니다. 이동 후 링크를 업데이트하고 사양을 중복하는 요약 문서를 피합니다.
코드 및 UI
- UI 코드를 편집하기 전에 사용자 동작을 상태 소유권을 따라 렌더링된 결과까지 추적합니다.
- 구체적인 불일치(중복된 프레젠테이션 상태, 일치하지 않는 이벤트/데이터 이름, 유효하지 않은 조건부 흐름, 이 변경으로 생성된 죽은 코드, 국소 수정을 차단하는 컴포넌트 책임)를 수정합니다.
- 사용자가 제품 또는 시각적 변경을 승인하지 않는 한 레이아웃, 상호 작용, 접근성, 반응형 동작을 안정적으로 유지합니다.
- 상태 전이의 명확한 소유자 하나와 데이터의 표준 표현 하나를 선호합니다. 입증된 필요 없이 추상화, 구성, 오류 처리를 도입하지 마십시오.
4. 아키텍처 후보는 별도로 평가
다음 용어를 일관되게 사용합니다.
- 모듈: 인터페이스와 구현이 있는 단위.
- 인터페이스: 호출자가 알아야 하는 모든 것(불변 조건 및 오류 모드 포함).
- 분할 지점: 호출자를 편집하지 않고 동작을 변경할 수 있는 곳.
- 깊이: 작은 인터페이스 뒤에 상당한 동작을 두는 전략; 국소성: 관련 지식과 변경이 함께 유지됨.
삭제 테스트를 적용합니다. 모듈을 삭제하면 복잡성이 호출자로 이동할 뿐이라면 그 가치가 있음; 복잡성이 사라진다면 얕을 가능성이 높음. 하나의 어댑터만을 위해 분할 지점을 만들지 마십시오.
인터페이스, 동작 또는 소유권을 변경하는 후보의 경우 즉시 구현하지 마십시오. 시각적 비교가 도움이 될 때만 OS 임시 디렉터리에 간결한 독립형 HTML 보고서를 만듭니다. 파일, 증거, 전후 다이어그램, 예상 국소성 및 활용, ADR 충돌(있는 경우), 권장 강도를 포함합니다. 인터페이스를 설계하기 전에 사용자에게 후보를 선택하도록 요청합니다.
5. 검증 및 인계
- 최종 diff를 검사하여 범위, 잠긴 콘텐츠 보존, 중복 진실 공급원, 의도하지 않은 값 또는 동작 변경 여부를 확인합니다.
- 기존 포매터, 린터, 타입 검사, 테스트, 빌드, UI 검증을 실행합니다. 이 작업만을 위해 도구나 광범위한 테스트 스위트를 추가하지 마십시오. 기존 실패와 도입된 실패를 구분합니다.
- 통합 후 마크다운 링크와 제목을 확인하고 각 변경된 문장을 정식 출처와 대조합니다.
- 직접 변경 사항, 해결되지 않은 결정 항목, 검증 결과, 위험을 간결하게 보고합니다. 변경된 모든 줄은 요청된 수렴으로 추적 가능해야 합니다.