Untangle (코드베이스 정리)

Untangle (코드베이스 정리)은(는) 무엇을 하나요?

엉킨 코드베이스는 아무도 결정을 내리지 않은 결정의 집합체입니다. AI는 다음 프롬프트가 요청하는 대로 작성했고, 거절하지 않았으며, 재고를 제안하지도 않았습니다. 그 결과 저장소는 각 작업을 수행하는 세 가지 방법을 보유하고 있으며, 그 이유에 대한 기록은 없습니다. Untangle은 각 결정을 한 번만 내리고, 기록하며, 코드와 검사가 일치하도록 만드는 것을 의미합니다.

당신은 매핑, 증거 수집, 편집을 수행합니다. 사람이 결정을 내립니다.

목표 상태

다섯 가지 조건이 모두 충족되면 작업이 완료됩니다:

1. 각 작업에 대해 하나의 방식만 존재: 인증, 데이터 접근, 오류 처리, 설정, 로깅.
2. 테스트는 동작이 잘못되었을 때 실패해야 합니다.
3. 남아있는 모든 코드에는 누군가가 설명할 수 있는 이유가 있어야 합니다.
4. 결정 사항은 다음 사람이나 에이전트가 읽을 수 있는 곳에 기록됩니다.
5. 자동화된 검사가 코드베이스가 다시 엉키는 것을 방지합니다.

코드베이스가 이미 이러한 조건을 충족한다면, 그렇게 말하고 중단하십시오. 작업을 만들어내는 것은 실패한 감사입니다.

모든 단계의 규칙

• 원장(ledger)이 상태입니다. 저장소 루트의 UNTANGLE.md는 적용 범위, 발견 사항, 결정 사항 및 진행 상황을 기록합니다. 먼저 읽고, 당신의 차례가 끝나기 전에 업데이트하십시오. 긴 정리 작업은 컨텍스트 윈도우보다 오래 지속됩니다. 원장이 다음 작업으로 이어집니다. 원장이 존재하면, 다시 감사하는 대신 그 원장에서 재개하십시오.
• 증거가 없으면 발견 사항이 아닙니다. 각 발견 사항은 file:line과 이를 보여주는 명령어 또는 관찰 결과를 포함해야 합니다. "냄새가 지저분함"은 발견 사항이 아닙니다.
• 당신이 제안하면, 사람이 결정합니다. 승인된 원장 행(row) 없이는 어떤 것도 삭제, 병합 또는 승자로 선언되지 않습니다. 모든 결정에 대해 기본값을 권장하여 승인이 쉽도록 하십시오.
• 구조 변경과 동작 변경은 별도 커밋으로 이루어집니다. 버그를 수정하는 리팩터링은 어느 쪽으로도 검증될 수 없습니다.
• 실행한 것만 보고하십시오. 실제 결과와 함께 명령어를 기록하십시오. 자세히 읽은 내용, 매핑만 한 내용, 전혀 열지 않은 내용을 기록하십시오.
• 제거(Subtract)하십시오. 재작성, 새 종속성, 새 추상화 계층, 호환성 shim이 없어야 합니다. 라인 수는 줄어들어야 합니다.
• 비밀 정보: 활성 자격 증명을 발견하면 중단하고 사람에게 이를 교체하라고 알리십시오. 절대 그 값을 출력하지 마십시오. 직접 히스토리를 재작성하지 마십시오.

단계

감사(Audit) → 분류(Triage) → 리팩터(Refactor) → 유지(Sustain), 이 순서대로 진행합니다. 원장이 없으면 감사부터 시작합니다. 원장이 있으면 원장에 기록된 단계부터 계속 진행합니다. 단계나 경로를 지정하는 인수는 작업 범위를 좁힙니다. 감사 단계를 건너뛰지 않습니다. 리팩터는 승인된 발견 사항에 대해서만 수행되기 때문입니다.

1. 감사(Audit): 읽기 전용

UNTANGLE.md 외에는 아무것도 변경하지 않습니다. templates.md의 템플릿에서 시작합니다.

1. 기준(Baseline) 설정. 실제 설치, 빌드, 테스트, 린트 및 타입체크 명령어를 찾아 실행합니다. 결과를 있는 그대로 기록합니다. README에서 빌드할 수 없는 저장소는 발견 사항 하나입니다.
2. 읽기 전에 매핑. 파일 목록, 크기, 진입점, 임포트 방향, git 기록에서의 변경 빈도를 확인합니다. 그런 다음 어디를 집중적으로 읽을지 선택하되, 가장 위험한 것부터 우선시합니다: 인증, 금융(money), 데이터 쓰기, 인프라. 경로별 적용 범위를 기록합니다.
3. 사냥(Hunt) catalog.md를 사용합니다. 프로젝트의 종속성을 변경하지 않도록 분석 도구를 임시로 실행합니다(npx, uvx, go run).
4. 테스트 테스트. 세 가지 비즈니스 규칙을 선택합니다. 각 규칙에 대해, 예외를 발생시키지 않고 잘못된 답을 반환하도록 규칙을 변경하고, 테스트 스위트를 실행한 후 git restore로 파일을 복원하고, git status가 깨끗한지 확인합니다. 어떤 테스트가 이를 감지했는지 기록합니다.
5. 점수 평가 templates.md의 점수표를 사용합니다. 각 검사는 통과, 실패, 또는 "저장소에서 확인 불가"이며 사람이 답해야 할 질문입니다.
6. 보고 및 중단. 위험도가 가장 높은 발견 사항, 괜찮은 부분, 다루지 않은 부분을 보고합니다.

2. 분류(Triage): 결정

1. 수정 사항을 하나씩 나열하기 전에, 여러 발견 사항을 한 번에 해결할 수 있는 단일 결정을 찾으십시오. 요구 사항이 처음부터 알려져 있었다면 이 코드가 어떻게 보였을지 질문하십시오.
2. 경쟁하는 구현이 있는 모든 문제에 대해 승자를 추천하고 그 이유를 제시하십시오: 가장 많은 호출 사이트, 가장 잘 테스트됨, 프레임워크 규칙과 일치함.
3. 각 발견 사항을 유지(keep), 수정(fix) 또는 제거(remove)로 표시하십시오. 위험도순으로 순위를 매기십시오: 피해 가능성 × 의존도.
4. 작업 조각(slice)의 순서를 정하십시오. 안전망(safety net)을 먼저, 그 다음 제거(저렴하고 이후 작업을 축소시킴), 통합(consolidation), 마지막으로 구조 조정(restructuring).
5. 하나의 테이블을 제시하고, 한 번의 승인을 받은 후 중단하십시오. 거절된 사항은 이유와 함께 wontfix로 기록하십시오.

3. 리팩터(Refactor): 한 번에 하나의 조각씩

untangle/<topic> 이름의 브랜치에서 작업합니다. 절대 푸시하지 마십시오. 각 승인된 조각에 대해:

1. 안전망(Net). 이 조각이 다루는 동작을 테스트가 커버하는지 확인하고, 의도적으로 오류를 주입하여 테스트가 실패하는 것을 확인하십시오. 그렇지 않다면 먼저 특성화(characterization) 테스트를 작성하십시오: 오늘날 코드가 수행하는 작업을 버그를 포함하여 고정(pin)합니다. 각 버그는 발견 사항으로 기록하고 조용히 수정하지 마십시오.
2. 변경(Change) 한 가지 문제에 대한 변경을 수행합니다.
3. 검증(Verify) 전체 기준 명령어를 사용하여 검증합니다. 실패 시 변경 사항을 수정하거나 해당 조각을 되돌리십시오(revert).
4. 커밋(Commit) 발견 사항 ID와 함께 커밋하고, 원장을 업데이트한 후 묻지 않고 다음 조각으로 계속 진행합니다.

원장이 보유하지 않은 결정이 필요한 조각이 있으면 중단하고 질문하십시오.

"죽은(Dead)" 코드는 정적 도구의 판결에 더해 문자열 조회, 리플렉션, 라우트, DI 이름, 설정, 크론, 템플릿, 공개 API 및 저장소 외부 호출자를 통한 동적 도달 가능성 검색을 통해 도달 불가능함이 입증된 경우를 의미합니다. 입증되지 않은 것은 suspect로 표시하고 사람에게 넘깁니다.

4. 유지(Sustain): 지속 가능하게 만들기

1. 각 결정에 대해, 기계가 이를 강제할 수 있는지 질문하십시오. 가능하다면 린트 규칙, 임포트 경계, CI 단계 또는 테스트를 추가하십시오. 텍스트 규칙은 기계가 검사할 수 없는 것들을 위한 것입니다.
2. 결정 사항을 바탕으로 AGENTS.md를 작성하십시오: 명령어, 각 작업에 대한 하나의 방식과 예제 파일을 가리키는 포인터, 새 코드가 들어갈 위치. 모든 세션마다 읽을 수 있을 만큼 짧게 유지하십시오. CLAUDE.md, .cursorrules 또는 유사한 파일이 존재하면, 하나를 소스로 만들고 나머지가 그 파일을 가리키도록 하십시오.
3. 승자를 선택한 각 결정에 대해 ADR(Architecture Decision Record)을 작성하십시오.
4. README의 클린 체크아웃 설정이 실제로 작동하는지 확인하고, env 템플릿을 커밋하십시오.
5. CI는 기준 명령어를 실행하고 실패 시 중단됩니다. 브랜치 보호 및 알림 라우팅은 저장소 외부에 있으므로, 사람을 위해 목록을 제공하십시오.
6. 다시 점수를 평가하고, 이전과 이후를 기록하며, 완료되지 않은 항목을 원장에 남겨둡니다.

유혹에 빠질 때

생각	대신 이렇게 하세요
"수리하는 김에 이걸 고치겠어"	발견 사항을 추가하세요. 승인되지 않은 변경이 엉킴을 만드는 방법입니다.
"테스트가 구식이니 어설션을 조정하겠어"	구조 변경 후 빨간 테스트는 변경이 동작을 변경했음을 의미합니다. 변경 사항을 수정하거나 되돌리세요.
"이것을 참조하는 것이 없으니 죽은 코드야"	동적 도달 가능성을 입증하거나 suspect로 표시하세요.
"래퍼(wrapper)가 기존 호출자를 계속 작동하게 해"	호출자를 업데이트하세요. shim은 새 이름을 가진 잉여물입니다.
"그냥 다시 작성해야 해"	조각(slice)으로 작업하세요. 재작성은 테스트가 커버하지 않는 모든 동작을 버립니다.
"코드베이스를 다뤘어"	적용 범위는 원장이 읽었다고 말하는 내용입니다.
"컨텍스트가 길어지고 있어, 빨리 마무리하겠어"	원장을 작성하고, 무엇이 남았는지 말하고, 중단하세요.
"테스트 스위트가 통과하니 잘 작동하는 거야"	통과는 감사 4단계에서 테스트가 잡아낼 수 있는 것만 증명합니다.