Innnteraction Architecture Guard
LLM의 구조 판단으로 통과 여부를 바꾸지 말고, 스크립트의 종료 코드와 기계 보고서를 따른다. 대상 코드를 import하거나 install·build·test script를 실행하지 않는다.
준비
- 대상 repository root를 확정한다.
scripts/architecture-guard.ps1 init --root <repo>또는scripts/architecture-guard.sh init --root <repo>를 실행한다.- 생성된
.architecture-guard/policy.json과reports/initialization.md의 제외 경로를 사람과 함께 검토한다. 상세 계약은 정책과 판정 계약을 읽는다. - 표시된 draft digest를 그대로 사용해
activate --accept-policy-digest <digest>를 실행한다. 기존 위반을 의도적으로 동결할 때만 사용자 승인 후--accept-existing을 추가한다.
정책을 자동 완화하거나 baseline에 위반을 자동 추가하지 않는다. sibling sg-reverse-engineer-service가 없거나 Python·JS/TS·Rust·Java 분석 capability가 부족하면 설치하지 말고 종료 코드 3을 보고한다.
개발 전 계획
- 사용자의 작업을 구현할 기존·신규 파일 경로 또는 기존
path#symbol로 좁힌다. 자연어만으로 경계를 추정하지 않는다. plan --path <path>또는plan --symbol <path#symbol>을 실행한다. 여러 대상은 옵션을 반복한다.- 새 경계 간 의존을 예상하면
--expect-dependency <from-boundary:to-boundary>를 추가한다. - 생성된 impact 보고서에서 직접 의존·역의존, 전이 영향 범위, 책임 경계, 규칙과 승인 필요 사유를 사용자에게 설명한다.
- 종료 코드가
11이면 구현을 시작하지 않는다. 정확한 정책 차이와 영향을 제시하고 사용자의 명시적 승인을 받은 뒤 draft 정책을 수정·재활성화하고 새 계획을 만든다.
여러 책임 경계를 계획에 포함했다는 사실만으로 실패시키지 않는다. 범위가 넓다는 관찰을 보고하고 계획 파일에 명시적으로 고정한다.
개발 후 검증
- 프로젝트 테스트를 실행하기 전에
verify --plan <plan.json>을 실행한다. - 계획 이후의 파일 hash와 현재 graph를 비교해 계획 밖 변경, 금지 방향, 공개 API 우회, 신규 순환, 미분류·중복 분류 모듈을 확인한다.
- 종료 코드
0일 때만 프로젝트의 가까운 테스트부터 실행한다. 10이면 코드 또는 계획 범위를 바로잡는다.11이면 정책·baseline 변경을 사용자에게 설명하고 승인 절차부터 다시 수행한다.
허용된 방향의 새 경계 간 의존은 보고하되 실패시키지 않는다. candidate·syntactic·dynamic edge는 참고 정보이며 통과·실패 근거로 사용하지 않는다.
수동 점검
- 계획 없이 현재 전체 graph를 검사하려면
check --root <repo>를 실행한다. - 사라진 baseline 위반은 자동 삭제하지 않는다.
check가 stale baseline으로 실패하면 내용을 확인한 뒤prune-baseline을 명시적으로 실행한다. .architecture-guard/는 로컬 작업 기록이다. 사용자가 명시적으로 요청하지 않으면 삭제하지 않는다.
종료 코드
0: 통과2: CLI·facts·policy·baseline·plan 오류3: 분석기 또는 필수 capability 없음10: 규칙 위반, 계획 범위 이탈, stale baseline11: 사용자 승인이 필요한 정책·baseline·구조 변경
LLM은 경로·symbol 탐색과 보고서 설명만 담당한다. 종료 코드를 무시하거나 통과·실패를 재판정하지 않는다.