Garbage Collection Agents — 시스템이 스스로를 유지하는 방법
핵심 아이디어
AC test가 새로운 위반을 막는다면, GC agent는 이미 쌓인 문제를 주기적으로 찾아낸다.
Drift란
3개월 전: "이 레이어 구조로 가자" → ADR-0002 작성
현재: 실제 코드는 조금씩 다른 방향으로 흘러감
ADR은 현실을 반영 못 하는 상태 → 아무도 모름
코드와 문서, 코드와 설계 의도가 서서히 벌어지는 현상. AC test는 새 commit을 막지만 이미 들어온 drift는 못 잡는다.
GC agent가 하는 세 가지 일
1. 문서 유효성 검사
ADR-0001: "SQLite 사용"
실제 코드: PostgreSQL 연결이 생겼다 → 불일치 알림
2. 아키텍처 위반 탐지
AC test가 잡지 못한 패턴:
- "이 모듈이 점점 커지고 있다"
- "순환 의존성이 생기기 시작했다"
- "이 레이어가 점점 뚱뚱해지고 있다"
3. 오래된 문서 정리
- feature_list.json에서 passes: true지만 실제로 깨진 항목
- docs/에서 6개월 이상 아무도 참조 안 한 파일
- 코드에서 삭제된 모듈을 여전히 참조하는 ADR
OpenAI의 구현 방식
주기적으로 돌고, PR로 제안한다. 직접 고치지 않는다.
GC agent 주기 실행 (매일 또는 매주)
↓
문서 ↔ 코드 불일치 발견
↓
"docs/adr/0001.md가 현재 코드와 맞지 않습니다" PR 생성
↓
인간이 검토 → merge or close
↓
(반복)
AC vs GC vs Git — 시간축 역할 분담
AC test: 새로운 위반이 들어오지 못하게 막는다 (예방, 실시간)
GC agent: 이미 들어온 drift를 찾아낸다 (치료, 주기적)
Git: 잘못됐을 때 돌아올 수 있게 한다 (복구, 사후)
왜 직접 고치지 않는가
GC agent가 자율적으로 수정하면:
- drift를 잘못 해석해서 멀쩡한 코드를 건드릴 수 있음
- 의도치 않은 변경이 연쇄적으로 발생할 수 있음
→ 제안만 하고 인간이 최종 판단. → 이게 "인간이 개입해야 하는 레이어"가 GC agent 결과 검토에 남는 이유.
Harness의 세 축 완성
Context Engineering → 올바른 정보를 올바른 타이밍에 넣는다
Architectural Constraints → 구조적 규칙을 기계적으로 강제한다
Garbage Collection → 시간이 지나며 생기는 drift를 찾아낸다
세 축이 서로 다른 문제를 다루면서 전체 시스템을 유지한다.
관련 개념
- overview — Harness Engineering 전체 지도
- architectural-constraints — AC와의 역할 분담
- context-engineering — 문서가 최신 상태여야 context가 의미 있다
- human-as-bottleneck — GC agent 결과 검토가 인간의 남은 역할 중 하나
GC agent의 실제 작동 방식
방식 1 — 전수 검사
문서 하나마다 전체 코드를 스캔. 단순하지만 비용이 크다. 소규모 프로젝트(파일 수십 개)에선 현실적.
방식 2 — 트리거 기반 (더 현실적)
git diff로 변경된 파일 추출
↓
변경 파일과 관련된 ADR만 찾기
↓
그 ADR ↔ 변경된 코드만 비교
이를 위해 ADR에 관련 코드를 명시:
# ADR-0001: SQLite 선택
## 관련 코드
- src/repo/database.py
- src/config/db_config.py
GC agent가 이 메타데이터로 "db.py 바뀌면 ADR-0001 확인" 매핑 생성. → 관련 없는 ADR은 검사 안 함.
방식 3 — LLM 기반 의미 검사
구조적 분석으론 못 잡는 미묘한 drift: "ADR은 레이어를 엄격히 분리하겠다고 했는데 코드가 점점 뒤섞이고 있다"
LLM이 코드와 ADR을 같이 읽고 판단. 비용이 크고 현재 실험적.
현실적인 도입 순서
1단계: git hook → 변경 파일 + 관련 ADR 알림 (LLM 없이, 단순 매핑)
2단계: 주기적 키워드 불일치 스캔 (간단한 스크립트)
3단계: LLM으로 의미적 drift 분석 (비용 크니까 나중에)
핵심: 전수 검사가 아니라 범위를 좁히는 것이 현실적. ADR에 관련 코드를 명시해두는 것 자체가 GC agent를 효율적으로 만드는 설계.