AI 에이전트를 개발에 통합하는 팀에서 ADR(Architecture Decision Record) 운용이 늘어나고 있습니다. 설계 판단을 팀에서 디스커션하여 결정하고, ADR로 도입합니다. 여러 명이 리뷰하고 승인하는 체제도 갖춰져 가고 있습니다.

하지만 그 리뷰에서 한 가지 관점이 빠지기 쉽습니다. 바로 ADR의 독자가 바뀌었다는 점입니다. 과거에는 ADR을 읽는 것이 인간이었습니다. 지금은 인간도 읽지만, AI에 읽혀서 코딩 시의 판단 기준으로 삼는 방식이 주류가 되어가고 있습니다. 인간의 리뷰를 통과한 ADR이라도 AI에게 모호하다면, 승인되는 순간부터 「모델마다 다른 규칙」으로서 움직이기 시작합니다.

이 기사에서는 ADR 도입 전에 거쳐야 할 「AI에 의한 해석 테스트」와 해석 오류가 일어나기 어려운 작성법을 정리합니다.

인간의 읽기 방식과 AI의 읽기 방식은 다르다

인간은 ADR을 읽을 때 팀의 문맥을 통해 행간을 보완할 수 있습니다. 「큰 파일은 분할한다」라고 되어 있다면, 이 팀에서의 「크다」라는 기준치를 경험을 통해 채울 수 있고, 망설여지면 다음 기회에 물어보면 그만입니다.

AI는 매번 백지 상태에서 문면만을 읽습니다. 기준치를 가지고 있지 않음에도 질문하지 않고 그럴듯한 해석을 확정 지어 구현을 진행합니다. 게다가 해석은 한 번으로 끝나지 않고, 세션마다·모델마다 다시 읽힙니다. 모호한 문면은 「읽을 때마다 다른 규칙이 될 수 있는 문면」입니다.

인간만이 독자였던 시대에 ADR의 모호함은 「나중에 물어보면 되는 보류 사항」이었습니다. AI가 주 독자가 된 지금은 「말없이 분기되는 사양 버그」입니다.

도입 전에 「해석 테스트」를 거칠 것

승인 전의 ADR을 AI에게 읽히면, 해석의 어긋남은 주로 세 가지 패턴으로 나타납니다.

오탐지(False Positive)의 어긋남: 어떤 모델은 위반이라고 판정하고, 다른 모델은 문제없다고 판정함 -
이해의 착오: 규칙의 주어나 적용 범위를 착각하여 의도와 반대되는 판단을 함 -
구속력의 분기: 「원칙」, 「권장」, 「가급적」을 절대 금지로 읽는 모델과 노력 목표로 읽는 모델로 나뉨 -

이를 도입 전에 검출하는 절차는 단순합니다.

• ADR 초안을 평소 개발에서 사용하는 모델을 포함한 여러 모델에게 읽힌다
• 동일한 질문을 한다 —— 「이 ADR에서 읽어낼 수 있는 규칙을 불렛 포인트로 복창해줘. 판단이 망설여지는 그레이 케이스(Gray Case)도 들어줘」
• 「이 코드는 이 ADR에 위반되는가?」라는 판정 문제를 OK 사례와 NG 사례 모두로 몇 문제 낸다
• 답변을 대조하여, 복창이 어긋난 부분이나 판정이 갈린 부분을 문면의 모호함으로서 수정한다

보는 것은 모델의 정답률이 아니라, 답변이 일치하는지 여부입니다. 모든 모델이 똑같은 오독을 한다면 문면이 그렇게 읽힌다는 증거이고, 갈린다면 문면이 해석을 확정 짓지 못했다는 증거입니다. 둘 다 ADR 측을 수정합니다.

소요되는 비용은 문의, 대조, 문면 수정까지 포함하여 1건당 30분 정도입니다. 모든 ADR에 적용하는 것이 무겁다면, AI의 코딩 판단에 직접 사용되는 ADR로 한정하는 것이 현실적입니다. 도입 후에 모호한 ADR이 몇 주간 작동하면, 그 ADR을 읽은 AI의 판단이 코드베이스에 축적되어 문면을 고쳐도 작성된 코드의 편차는 남게 됩니다. 도입 전의 30분이 훨씬 저렴합니다.

작성법 1: 구체적인 예시는 반드시 양쪽을 모두 작성할 것

구체적인 예를 하나만 쓰고 만족하면, 경계선을 모델이 마음대로 긋습니다.

NG 사례만 있는 ADR:
「거대한 함수는 분할한다. 예: 300행의 함수는 분할 대상」

300행이 분할 대상이라는 점은 모든 모델이 일치합니다. 갈리는 지점은 80행, 120행, 200행입니다. NG 측의 예시만 있기 때문에, 「어디서부터 세이프인가」를 각 모델이 독자적으로 보완합니다.

양쪽을 모두 작성한 ADR:
「함수는 100행 이하로 유지한다.
OK 예시: 95행의 함수는 그대로 두어도 좋다
...

OK 측과 NG 측 양쪽에 값을 배치하면, 경계선은 문면이 그은 것이 되어 모델의 보완 여지가 사라집니다. 동기/비동기, 공개/비공개와 같은 2분류 규칙도 마찬가지로, 한쪽 조건만 쓰고 「그 외에는 다른 쪽」이라고 읽히게 하지 말고, 양쪽 분류에 해당하는 구체적인 값을 각각 명기합니다.

작성법 2: 상대어를 버리고, 양쪽을 지칭할 것

「상위」, 「새로운」, 「큰」과 같은 상대어는 독자가 기준점을 가지고 있다는 전제의 단어입니다.

상대어를 사용한 ADR:
「상위 레이어에서 하위 레이어로의 의존성만 허용한다」

팀 멤버는 자신들의 레이어 구성을 알고 있으므로 망설이지 않습니다. AI는 「이 프로젝트에서 무엇이 상위인가」를 코드로부터 추측해야 하며, 프레젠테이션 레이어와 유스케이스 레이어 중 어느 쪽이 위인지와 같은 판단이 모델마다 흔들립니다.

상대적인 용어를 사용한다면 기준을 고정해야 합니다(예: 「레이어의 상하 관계는 본 ADR 끝부분의 도표와 같음」 등). 더 확실한 방법은 상대적인 용어 자체를 버리고, 포함하는 쪽과 포함되는 쪽을 구체적인 명칭으로 지칭하는 것입니다.

지칭한 ADR:
「service 계층(포함하는 쪽)은 repository 계층(포함되는 쪽)을 import 해도 된다.
repository 계층에서 service 계층로의 import는 금지한다.
...

「상위/하위」라는 상대적 관계를 고유 명사 쌍으로 교체하고, 허용되는 방향과 금지되는 방향을 모두 작성합니다. 작성법 1과 동일한 구조입니다. 관계에는 양방향이 존재하므로, 한쪽 방향만 작성하면 모델이 역방향에 대한 처리를 보완하게 됩니다.

지칭을 선택했을 때의 대가는 범용성입니다. 레이어 이름을 바꾸면 ADR도 수정해야 합니다. 그럼에도 지칭하는 방식을 택하는 이유는 ADR의 목적이 「판단의 재현」이기 때문입니다. 독자에 따라 재현되지 않는 범용 원칙보다, 이 프로젝트에서 확실하게 재현되는 고유 규칙이 더 가치가 있습니다.

작성법 3: 확정에 도움이 되지 않는 문장은 삭제한다

양방향의 예를 작성하면 ADR은 길어지지만, 길이가 무제한으로 허용되는 것은 아닙니다. ADR은 코드, 다른 ADR, 작업 지시와 함께 컨텍스트 (Context)에 쌓이므로, 길이 그 자체가 비용입니다.

컨텍스트 예산의 압박: ADR이 10개이고 각각 3,000자라면, 매 세션마다 3만 자가 규칙 독해에 소모됩니다 -
중간 부분의 감쇠: 긴 입력값의 중간은 처음이나 끝보다 참조되기 어렵습니다 (이른바 lost in the middle). 결정의 본체가 긴 경위 설명 뒤에 묻히게 되면, 경위는 읽혔지만 결정 사항은 누락될 수 있습니다 -
규칙의 희석: 읽어야 할 지시의 총량이 늘어날수록, 한 개당 준수율은 떨어집니다

원칙은 하나입니다. 늘려도 좋은 것은 경계를 확정하는 문장뿐이며, 확정에 도움이 되지 않는 문장은 삭제한다입니다.

• 하나의 ADR에는 하나의 결정만 담는다. 섞여 있다면 분할한다.
• 구체적인 예시는 각 측면당 하나씩, 경계가 확정된다면 그 이상 나열하지 않는다.
• 디스커션 (Discussion)의 경위나 기각된 대안의 상세 내용은 본문에서 분리하여 링크로 연결한다 (인간은 따라갈 수 있지만, AI의 매번의 컨텍스트에는 포함되지 않도록 함).
• AI에게 상시 읽히는 ADR 본문은 한 개당 수백 자에서 천 자 정도를 기준으로 한다.

경위를 분리하면 「왜 이 결정에 이르렀는가」에 대한 설득력은 본문에서 약해집니다. 인간인 신규 멤버에게는 경위야말로 가치 있는 정보이므로, 링크는 반드시 남겨두어야 합니다.

도입 전 체크리스트

• 여러 모델에게 규칙을 복창하게 하여, 복창 내용이 일치하는가
• OK 예시·NG 예시 판정 문제를 내어, 판정이 갈리지 않는가
• 구체적인 예시에 OK와 NG(2분류라면 양쪽 분류 모두)의 값이 있는가
• 「상위」, 「크다」, 「새롭다」 등의 상대적인 용어가 남아있지 않은가
• 상대적인 용어를 지울 수 없는 경우, 기준이 ADR 내에서 고정되어 있는가
• 관계를 작성할 때, 포함하는 쪽과 포함되는 쪽을 지칭하여 양방향 처리를 명기했는가
• 하나의 ADR에 결정이 하나만 담겨 있는가
• 경위나 기각안의 상세 내용이 본문에서 분리되어 있는가

ADR의 리뷰 관점에 「인간이 납득하는가」에 「AI가 동일한 해석에 도달하는가」가 추가되었습니다. 해석 테스트라고 해도, 하는 일은 ADR의 문면을 AI에게 전달하여 질문하는 것뿐입니다. 다음 ADR 디스커션에서, 승인 직전 단계에 한 번 끼워 넣어 보세요.

Discussion