Sg Review Arch

Assess Software Architecture

현재 구조의 사실과 목표 구조에 대한 판단을 분리한다. 인기 있는 패턴을 정답으로 두지 말고 제품 콘셉트, 품질 목표와 예상 변화에 맞는 구조인지 평가한다. 전체 코드를 순서대로 읽지 말고 기계 분석으로 범위를 좁힌다.

시작

1. 소스 저장소 루트, 프로젝트·manifest 루트, 배포 단위, 분석 루트, package root, revision, dirty 상태와 접근 제한을 구분해 기록한다. 같은 경로가 여러 의미를 가져도 용어를 합치지 않는다.
2. 제품 가치와 actor, 초기 제품 콘셉트, 중요한 품질 목표 최대 3개, 대표 변경 시나리오를 확인한다. 자료가 없으면 추론과 질문을 분리해 기록한다.
3. 동일 revision의 docs/reverse-engineering/ 자료가 있으면 증거로 재사용하되 현재 source digest 또는 commit과 다르면 갱신 전까지 stale로 표시한다.
4. 평가 기준이 필요하면 평가 루브릭을 읽는다. 보고서를 만들거나 갱신하기 전에는 문서 계약을 읽는다.

기계 분석으로 읽기 범위 줄이기

1. 임시 디렉터리를 만든다.
2. Windows에서는 scripts/analyze-architecture.ps1 -Root <repo> -Output <temp>/architecture-facts.json -EvidenceOutput <target>/docs/architecture-evidence.md, macOS·Linux에서는 scripts/analyze-architecture.sh --root <repo> --output <temp>/architecture-facts.json --evidence-output <target>/docs/architecture-evidence.md를 실행한다.
3. wrapper는 sibling sg-reverse-engineer-service의 discover, 구조 요약기와 결정적 Markdown renderer를 차례로 실행한다. Python·JS/TS·Rust·Java capability를 그대로 보존하며 의존 Skill이나 런타임이 없으면 자동 설치하지 않는다.
4. 저장할 기계 증거 Markdown의 snapshot, capability, scope, diagnostics, boundary, cycle, change coupling과 read_set을 먼저 검토한다. 원시 module·edge 전체나 임시 JSON을 대화 컨텍스트에 복사하지 않는다.
5. manifest, README, ADR과 read_set의 파일·symbol 범위만 우선 읽는다. package 하위 경로가 root면 ancestor-context-discovery가 제시한 가장 가까운 manifest·README·tests도 제품 context로만 확인하고 구조 graph 범위와 섞지 않는다. 경계가 불명확할 때만 다음 후보를 추가한다.
6. nested-typescript-project-uncovered가 있으면 루트 TypeScript program에 포함되지 않은 별도 tsconfig의 production source를 구조 graph 밖 coverage로 표시하고, 해당 project의 진입점·계약·대표 module을 제한적으로 별도 읽는다. 누락 범위를 전체 구조 지표에 포함된 것처럼 표현하지 않는다.
7. 분석 루트 자체가 Python import package라면 요약기는 <root-name>.* 절대 import를 알려진 module에 한해 내부 의존 관측으로 재분류한다. package-root-import-rebinding capability와 재분류 관측 수를 확인하고, 외부 의존을 모두 내부로 간주하지 않는다.
8. 대표 성공 경로와 구조적으로 중요한 실패·비동기 경로에만 sibling 분석기의 trace를 실행한다. Python package root에서 trace가 한 module에 머물면 가장 가까운 상위 프로젝트·manifest 루트를 trace 기준 경로로 사용하고 entry path에 package 이름을 붙인다. 구조 요약의 분석 범위 자체는 넓히지 않는다. 큰 trace는 depth와 node 수를 제한한다.
9. 많은 router나 큰 순환군은 파일 전체를 읽지 않는다. read_set이 고른 경계·종류별 대표 entrypoint의 symbol 범위, 순환군의 경계별 대표, fan-in/out hub부터 읽고 필요한 frontier만 확장한다. entrypoint_reachability는 실제 요청 trace가 아니라 module-dependency-closure이므로 런타임 호출 범위로 표현하지 않는다.
10. 원시 JSON은 임시 위치에만 두고, 작업 후 자신이 만든 정확한 임시 경로만 제거한다. 결정적으로 생성한 architecture-evidence.md는 평가의 재현 가능한 기계 근거로 저장한다.

대상 모듈을 import하거나 install/build script를 실행하지 않는다. 설정값, SQL 본문, 소스 리터럴, Git author와 commit message를 산출물에 복사하지 않는다.

구조 재구성과 평가

1. Context와 Container 수준에서 actor, 외부 시스템, deployable, 데이터 저장소와 책임을 재구성한다.
2. package·workspace·deployable·디렉터리 경계 후보를 코드·manifest·배포·소유권 증거와 대조해 실제 책임 경계를 정한다. 디렉터리 이름만으로 경계를 확정하지 않는다. 기본 집계에서 제외된 test·fixture·example scope는 제품 구조와 별도로 검토한다.
3. canonical 구조 문서의 규모·책임·진화 단계가 현재 module·entrypoint·deployable 사실과 맞는지 확인한다. 불일치는 구현 결함으로 단정하지 말고 문서 drift와 제품 콘셉트 불확실성을 분리해 기록한다.
4. 기계 지표는 조사 우선순위로 사용한다. cycle, fan-in/out, change coupling만으로 설계 위반을 단정하지 않는다.
5. 물리적 source 경로, build·deploy 경계, 논리적 책임 경계와 패턴 역할을 같은 수준처럼 섞지 않는다. root, repository, service를 단독으로 쓰지 말고 문서 계약의 용어를 사용한다.
6. 제품 목표 정렬, 책임과 응집, 의존 방향, 계약과 데이터 소유권, 독립 변경·테스트·배포, 장애 격리, 에이전틱 작업 국소성, 드리프트 방지를 평가한다.
7. 항목별로 적합, 주의, 부적합, 미확인, 신뢰도 높음, 중간, 낮음, 제품 영향 우선순위 P0~`P3`를 서로 분리해 기록한다. 총점은 만들지 않는다.
8. 패턴은 의존 방향, 상태 소유권, 호출 흐름, 공개 계약 등 복수 증거가 맞을 때만 확인, 부분 적용, 명목상 적용, 충돌, 미확인으로 판정한다. 일반적인 적용 규모·잘 맞는 상황·현재 관찰 범위를 함께 적고 일부 적용을 전체 아키텍처로 확대하지 않는다.
9. 현재 구조에서 유지할 부분과 바꿀 부분을 구분하고 하나의 권장 목표 구조를 제시한다. 서로 다른 품질 제약을 최적화하는 근거가 있으면 조건부 2안까지 제시하되 선택 조건·trade-off·재검토 신호를 분리한다. 근거가 없으면 억지로 2안을 만들지 않는다.
10. 각 개선안을 문제 → 증거 → 제품·품질 영향 → 목표 경계 → 전환 단계 → fitness function으로 연결한다.

산출물

기본 산출물은 자동 생성하는 docs/architecture-evidence.md와 사람이 검토하는 docs/architecture-assessment.md다. 전자는 동일 facts에서 byte-stable해야 하며 직접 편집하지 않는다. 후자의 claim은 AA-001 형식을 사용하고 사실, 평가, 제안을 구분하며 기계 사실은 evidence 문서의 안정된 anchor를 참조한다.

핵심 결론은 P0 → P1 → P2 → P3 → 강점 → 중요 미확인 순으로 정렬한다. 첫 문장은 짧게 쓰고 필요한 경우에만 증거·영향·다음 판단을 한 단계 하위 목록으로 둔다. 평가 매트릭스 앞에는 등급 신호등과 신뢰도 점 표기를 설명하는 별도 범례를 둔다. 상세 형식은 문서 계약을 따른다.

유지보수·에이전틱 코딩 평가는 앞선 평가 축과 패턴을 대표 변경 시나리오에 연결해 nested list로 간결하게 설명한다. 권장 목표 아키텍처의 각 안에는 별도 다이어그램과 경계 책임·허용 방향 설명을 붙이고, 두 안이 있으면 비교표로 현재 권장안을 명확히 한다.

edge 수를 제시할 때는 관측(occurrence)과 정규화된 관계(edge)를 구분한다. 원시 관측, 구조 의존 관측, 내부 재분류 관측, 정규화된 module dependency의 처리 순서와 포함 관계를 설명하고, 내부 재분류 관측을 별도 graph 크기처럼 더하거나 빼지 않는다. 정적 edge는 런타임 호출 횟수가 아님을 명시한다. 상세 용어와 표 형식은 문서 계약을 따른다.

중첩 경계나 동음이의 역할이 있으면 snapshot 다음에 용어·경계 hierarchy를 제공한다. 소스 저장소는 소스 저장소, DB 접근 패턴은 영속성 Repository, wiring 역할은 구성 진입점(composition root)으로 표기한다. 기계 결과의 (analysis-scope)는 전체 분석 범위, (analysis-root-files)는 분석 루트 직속 파일을 뜻한다.

충분한 증거가 있으면 다음 관점 중 최소 네 가지를 Mermaid로 제공한다.

• 시스템 Context
• Container·배포 구조
• 모듈·경계 의존과 순환
• 권장 목표 아키텍처
• 대표 성공·실패·비동기 sequence
• 데이터 소유권과 읽기·쓰기 경계
• Git change coupling
• 목표 구조로 이동하는 단계와 배포·장애 격리 구조

flowchart, sequenceDiagram, stateDiagram-v2를 사용한다. 각 그림에 관점, snapshot, 확인·추론·미확인 범례를 둔다. 전체 module graph를 그대로 그리지 말고 경계 단위로 집계한다. 근거가 부족한 관점은 개수를 맞추기 위해 만들지 말고 생략 이유를 기록한다.

완료 확인

• 제품 콘셉트와 품질 목표가 평가 기준보다 먼저 제시되었는지 확인한다.
• 핵심 결론과 평가 행이 제품 영향 우선순위대로 정렬되었는지 확인한다.
• 등급·우선순위·신뢰도의 의미가 분리되고 범례로 설명되었는지 확인한다.
• 패턴의 일반적 적용 규모와 현재 관찰 범위가 구분되었는지 확인한다.
• 소스 저장소·분석 루트·package root·배포 단위·구성 진입점·영속성 Repository가 혼동 없이 구분되었는지 확인한다.
• 유지보수·에이전틱 평가가 6·7장의 판단을 실제 변경 비용과 검증 loop로 번역했는지 확인한다.
• 목표안이 최대 두 개이며 각 안의 선택 조건·다이어그램·설명·비용이 있고 현재 권장이 명확한지 확인한다.
• 현재 사실, 규범적 평가와 목표 제안이 구분되었는지 확인한다.
• 주요 판단과 제안이 revision이 고정된 evidence에 연결되었는지 확인한다.
• 기계 증거와 평가 보고서의 source digest가 같고 평가 claim이 evidence anchor를 참조하는지 확인한다.
• 기계 지표의 한계와 동적 경계를 사실처럼 표현하지 않았는지 확인한다.
• edge 관측 수와 정규화된 dependency 수의 단위·포함 관계·중복 제거 기준을 설명했는지 확인한다.
• 제한된 read_set으로 결론을 설명할 수 있는지 확인한다.
• 전환 단계마다 동작 보존 방법과 검증 가능한 fitness function이 있는지 확인한다.
• 다이어그램들이 같은 구조를 반복하지 않고 서로 다른 질문에 답하는지 확인한다.