도구

AI Agent의 코드를 되돌릴 때 필요한 결정 기록

ADRs for AI는 Agent의 선택지, 추천 근거, 확신도, 반증 조건을 Git에 기록해 코드 diff만으로 알 수 없는 맥락을 보존한다. ORRCF와 사람의 승인·수정 절차를 함께 활용하면 AI 의사결정을 검토 가능한 Engineering Context로 바꿀 수 있다.

글자 크기

AI Agent는 한 번에 십여 개 파일을 수정할 수 있지만, 커밋 후 남는 것은 보통 commit message와 diff뿐이다. 무엇을 바꿨는지는 설명할 수 있지만, 왜 이 방식을 선택했는지, 모델이 어느 지점에 확신이 없었는지, 같은 작업을 다시 실행했을 때 같은 결과가 나오는지는 답하기 어렵다.

Git은 코드의 사실을 기록하지만 완전한 의사결정 과정은 남기지 않는다. ADRs for AI는 이 공백을 메우기 위해 모델의 판단 근거를 Git에 기록하고, ORRCF 형식을 통해 Agent의 우려를 드러내도록 요구한다.

진짜 빈칸은 코드가 아니라 의사결정 기록

예를 들어 Agent에게 동기 작업을 비동기 큐로 전환하라고 지시했다고 하자.

최종 diff는 몇 줄에 불과할 수 있다. producer, consumer, retry policy를 추가하고 기존의 blocking call을 제거하는 정도다.

코드 리뷰에서는 race condition, message loss, duplicate consumption을 확인할 수 있지만, 리뷰어에게 전체 의사결정 체인은 보이지 않는다.

  • 왜 Kafka 대신 Redis Streams를 선택했는가?
  • 왜 기존 데이터베이스를 source of truth로 유지했는가?
  • 작업 지연과 운영 복잡성을 함께 평가했는가?
  • 어떤 현상이 나타나면 이 선택이 틀렸다고 판단해야 하는가?

Agent가 참여하면 이런 질문들은 “best practice에 따라 최적화했습니다”라는 한 문장으로 압축되기 쉽다.

일반적인 ADR은 원래 이러한 질문을 남기기 위한 도구다. 가벼운 의사결정 기록으로, Nygard의 고전적인 형식은 보통 Context, Options, Decision, Consequences로 구성된다. 팀은 어떤 기술 경로를 선택했는지와 그 이유를 남긴다. 이후 담당자가 논의에 참여하지 않았더라도 현재 코드가 왜 그렇게 만들어졌는지 이해할 수 있다.

ADRs for AI는 여기에 두 가지 변경을 더했다.

첫째, ADR을 사람과 AI가 함께 일하는 환경으로 확장했다. AI Agent는 의사결정 제안의 작성자가 될 수도 있고, 이후 만들어진 의사결정 기록을 읽을 수도 있다.

둘째, 이러한 Architectural Deliberation Records를 Git에 저장한다. 기록은 대화창과 함께 사라지지 않고 버전 관리에 들어가 코드와 함께 리뷰, 커밋, rollback된다.

자연어 설명이 대화창에만 남아 있다면 그저 로그일 뿐이다. Git에 넣은 뒤에는 함께 협업할 수 있는 Engineering Context가 될 수 있다.

ORRCF: 모델이 먼저 제출해야 할 다섯 가지

ADRs for AI는 ORRCF 형식으로 모델의 의사결정 제안을 정리한다.

  1. Options: 유지할 수 있는 선택지는 무엇인가. 현상 유지를 포함한다.
  2. Recommendation: 모델이 추천하는 선택지는 무엇인가.
  3. Rationale: 왜 그 선택지를 추천하며 어떤 대안을 포기했는가.
  4. Confidence: 모델이 추천 결과에 대해 어느 정도 확신을 갖는가.
  5. Falsifier: 어떤 근거가 확인되면 이 추천이 성립하지 않는다는 뜻인가.

설명 템플릿처럼 보이지만这只是 출력을 더 완전하게 만들기 위한 장치가 아니다.

ORRCF는 모델이 자신의 우려를 드러내고, 제안된 판단을 사람이 승인하거나 덮어쓸 수 있도록 요구한다. 모델은 코드를 제출한 뒤 정중한 요약만 붙이는 것으로 끝내지 않는다. 먼저 리뷰 가능한 의사결정 제안을 제출해야 한다.

예를 들어 비동기 큐 작업의 제안은 다음과 같이 작성할 수 있다.

## Options

1. 保留同步调用
2. 使用 Redis Streams
3. 使用 Kafka

## Recommendation

使用 Redis Streams。

## Rationale

当前吞吐量不需要 Kafka 的分区和运维成本。
Redis Streams 已提供 consumer group、确认机制和消息保留。

## Confidence

中高。主要不确定性是现有重试逻辑迁移后的幂等性。

## Falsifier

如果压测中 consumer lag 持续增长,或重投导致重复处理,
则当前方案不成立,应重新评估 Kafka。

사람은 이를 승인하거나 모델의 추천을 덮어쓸 수 있다. 덮어쓴 이유도 ADR에 남길 수 있다. 다음번 Agent는 코드뿐 아니라 팀이 이미 내린 선택과 그 배경까지 읽을 수 있다.

이렇게 하면 지속 가능한 AI programming scaffold를 만들 수 있다. 현재 제안뿐 아니라 팀이 그 제안을 수정한 과정도 보존된다. 이후 작업에서는 승인된方案, 거부된方案, 조건이 붙은方案을 맥락으로 활용할 수 있다.

모든 commit마다 긴 문서를 작성하라는 요구는 아니다. 위험이 높거나 비용이 큰 변경, 또는 diff만으로 이해하기 어려운 변경에 의사결정 검사를 추가하는 편이 적합하다.

ADR을 Git에 넣어야 협업 가능한 맥락이 된다

많은 Agent 도구는 이미 코드 검색에 능하다. 먼저 관련 파일을 찾고, symbol 정의를 읽고, 호출부를 검색한 다음 구현을 수정한다.

ADR은 다른 층위의 검색을 보완한다. 어떤 선택지가 이미 논의되었고, 어떤 경계 조건에서 문제가 발생했는지를 찾는 역할을 한다.

첫 번째 데이터베이스 마이그레이션에서 트래픽이 적다는 이유로 SQLite를 선택했다고 하자. 이후 트래픽이 늘어 PostgreSQL로 전환하기로 결정했다. ADR에는 두 차례의 기록이 모두 있어야 한다.

  • 처음에 SQLite를 선택한 이유.
  • 나중에 PostgreSQL로 마이그레이션한 이유.
  • 어떤 가정이 더 이상 유효하지 않게 되었는가.
  • 어떤 제약은 여전히 유지되는가.

현재 코드만 읽는 후속 Agent는 과거 선택을 우연한 구현으로 받아들일 수 있다. ADR을 읽으면 당시의 제약을 최소한 확인할 수 있다.

Git은 다음 세 가지 협업 특성도 제공한다.

첫째, 의사결정과 구현을 함께 리뷰할 수 있다. 리뷰어는 코드와 나란히 비교해 모델이 약속한 내용을 실제로兑现했는지 확인할 수 있다.

둘째, 의사결정을 되돌릴 수 있다. 구현이 잘못되었다면 diff를 rollback할 수 있다. architecture 선택이 잘못되었다면 과거를 지우는 대신 새로운 ADR로 대체 관계를 명확히 남길 수 있다.

셋째, 책임 범위가 선명해진다. 사람이模糊한 “모델이 이미 처리했습니다”라는 결과를 떠안는 대신, 명시적인 제안에 대해 승인하거나 수정한다.

다만 ADR은 테스트, 코드 리뷰, architecture discussion을 대체하지 않는다. 이 활동들이 참조할 수 있는 공통 기준을 하나 더할 뿐이다.

반론: 기록이 많아진다고 감독이 강해지는 것은 아니다

구조화된 형식을 Agent workflow에 연결하면 보기 좋은 결과를 만들기 쉽다. 모든 작업에 Options, Rationale, Confidence, Falsifier가 추가되는 것이다.

하지만 이것이 단지 형식주의일 수도 있다.

Confidence는 신뢰하기 어렵다. 모델이 “0.8”을 제시한다고 해서 결과가 80%的 확률로 정확하다는 뜻은 아니다. training data의 표현 습관, prompt template, 심지어 작업 난이도에 따라 이 숫자가 바뀔 수 있다. 설명이 필요한 신호일 뿐이다.

Falsifier 역시 test와 같지 않다.

모델이 “consumer lag가 지속적으로 증가하면方案이 실패한 것”이라고 적었다고 해서, 실제 부하 테스트를 작성했거나 팀이 증가 임계값을 알고 있다는 뜻은 아니다. 아무도 실행하지 않는 반증 조건은 불확실성을 더 격식적인 언어로 바꿔 놓을 뿐이다.

따라서 ADR의 품질은 engineering evidence로 되돌려야 한다.

  • Rationale은 실제 제약을 인용하는가, 아니면 모호한 best practice를 반복하는가?
  • Recommendation은 실제 코드 변경과 일치하는가?
  • Falsifier는 실행 가능한 test나 monitoring metric과 연결되어 있는가?
  • 사람이 모델의 제안을 덮어썼다면 그 이유를 기록했는가?
  • 후속 Agent가 과거 ADR을 실제로 읽고 활용했는가?

더 미묘한 문제도 있다. 기록이 감독의 환상을 만들 수 있다는 점이다.

문서가 완성될수록 리뷰어는 의사결정이 이미 적절하게 처리되었다고 느끼기 쉽다. 하지만 ORRCF가 작업 종료 시 자동으로 생성되는 template이라면 코드를 설명하는 데 그치지 않고 단순히 되풀이했을 가능성이 크다.

유용한 ADR은 사람이 불일치를 발견할 수 있어야 한다.

예를 들어 모델은 DB lock 경쟁을 피하려고 Redis를 추천했다. 실제 코드에서는 transaction 안에서 상태 테이블을 갱신하고 있다. 사람은 이를 보고 제안과 구현 사이에 차이가 생겼음을 바로 알아차릴 수 있다.

“모델이 자신 있게 작업을 완료했다고 말하는 것”보다 훨씬 유용한 신호다.

따라서 ADRs for AI는 quality assurance interface보다 audit interface에 가깝다. AI의 제안을 검사하기 쉽게 만들지만, 제안을 자동으로 더 정확하게 만들지는 않는다.

원 프로젝트의 설명은 ADRs for AI 프로젝트 웹사이트와 Hacker News 논의를 참고할 수 있다. 프로젝트는 Architectural Deliberation Records, ORRCF 다섯 항목 형식, 사람의 승인·수정 mechanism, Git 기반의 지속 가능한 AI programming scaffold를 소개한다.

편집자 생각

ADRs for AI의 가치는 “AI를 기록하는 것”에 있지 않다. 모델의 제안을 감사 가능한 engineering object로 바꾸는 데 있다. 코드는 현재 시스템이 무엇인지를 설명하고, ADR은 그렇게 바뀐 이유를 설명한다. 둘이 같은 Git history에 들어가면 이후의 엔지니어와 Agent는 의사결정 맥락을 이어받을 수 있다.

ORRCF의 단기 가치는 자율 능력보다 review interface에 mainly体现在那里. Agent를 반드시 더 똑하게 만들지는 않지만, 불일치를 더 일찍 드러낼 수 있다. 추천과 코드가 다르거나, 반증 조건에 대응하는 test가 없거나, 사람의 수정 이유가 남아 있지 않은 경우를 발견할 수 있다. 팀이 이것을 자동 회의록처럼만 사용한다면 곧 문서 부담이 된다.

이 방식은 과거 AI programming 도구와 다르다. 예전에는 주로 코드와 test를 completion했다. 이제 Agent는 여러 파일에 걸친 변경을 수행하며 의사결정의 범위가 더 넓어졌다. 공개된 자료는 production 환경의 효과, 프로젝트 규모, 오류율 변화를 제시하지 않으므로 성숙도는 여전히 검증해야 한다. 중요한 것은 ADR이 얼마나 보기 좋은지가 아니라,半年 후 새로운 Agent가 과거의 실수를 한 번이라도 덜 반복할 수 있는지다.

출처: https://adrs.systems