IDR은 구현보다 결정의 의도를 남겨야 한다

repo-parser에서 DuckDB를 중간 표현으로 쓰도록 요청한 IDR은 “어떤 방식으로든 DuckDB를 쓰라”는 말에 가까웠다. 윌 라샹스(Will Lachance)는 이런 기록이 의도보다 변경 사항을 다시 설명하는 데 그칠 수 있다고 봤다.

라샹스는 Writing the Docs: 2026 Edition에서 구현 결정 기록(IDR)을 소개했다. 그는 IDR이 대규모 언어 모델의 결과를 개선하고, 기능을 구현하는 동안 내린 결정을 오래 남기는 데 쓰일 수 있다고 주장한다. 특히 모델을 활용해 코드를 작성하거나 나중에 저장소의 결정 배경을 다시 확인하려는 사람에게 어떤 내용을 기록할지가 중요하다는 이야기다.

IDR은 기능을 구현하면서 내린 결정과 그 의도를 문서로 남기는 방식이다. 소프트웨어 구조에 관한 결정을 기록하는 아키텍처 결정 기록(ADR)에서 이름을 따왔다.

IDR이 무엇을 남겨야 하나

라샹스가 처음 든 예시는 repo-parser의 중간 표현을 DuckDB로 바꾸는 기록이다. 문제 설명은 저장소에서 추출한 메타데이터를 메모리 안의 Resource 트리에 담지만, 사용하는 도구마다 다시 만들어야 한다고 적었다. 여러 도구가 저장소를 다시 훑지 않고도 메타데이터를 쓸 수 있도록 지속적이고 질의 가능한 직렬화 형식이 필요하다는 내용이다. 그는 이 설명이 아주 나쁘지는 않지만, 에이전트에게 “어떤 식으로든 DuckDB를 사용하라”는 것 이상의 목표를 충분히 주지 못했다고 본다. 해당 IDR

그 결과물도 괜찮은 편이었지만, 라샹스는 IDR이 실제로 얼마나 도움이 됐는지 의문을 제기한다. 문서는 repo-parser의 DuckDB 출력이 저장소 내용의 BM25 검색 색인이나 터미널 사용자 인터페이스 검색 도구에 유용할 수 있다는 점을 설명하지 못했다. 그는 나중에 다시 읽고 싶지 않을 정도로 문서가 장황하고, 결국 변경 사항을 영어로 풀어 쓴 것과 크게 다르지 않다고 평가한다.

더 나은 기록은 어떻게 쓰나

라샹스가 더 만족한 예시는 GitHub Actions를 통해 PyPI에 배포하는 방법을 다룬 IDR이다. 수동 배포는 시간이 들고 오류가 나기 쉬우며, GitHub Actions를 이용하는 것보다 보안성이 낮다는 문제를 먼저 적었다. 목표는 새 버전 배포를 쉽게 하고 보안을 개선하는 것이다. 버전 올리기는 자동화하지 않고 별도 커밋으로 남긴다는 비목표도 명시했다. 해결책은 공식 패키징 안내를 따르고, 새 릴리스에 맞춰 PyPI 업로드를 실행하는 GitHub 워크플로를 추가하는 것이었다. 해당 IDR

라샹스가 중요하게 보는 차이는 기록이 의도와 결정을 계속 가리키는지다. 문제 설명은 왜 변경하려는지 밝히고, 목표·비목표·해결책은 원하는 결과를 짧고 구체적으로 정한다. 구현 세부 사항까지 기록하기보다 모델이 목표를 잘못 해석하지 않도록 방향을 잡고, 더 필요한 정보는 변경 내역(diff)에서 확인하는 편을 선호한다. 그는 커밋 메시지를 만들 때도 뚜렷한 지침이 없으면 모델이 비슷한 방식으로 내용을 채울 수 있다고 덧붙인다.

IDR이 실제로 모델의 결과를 얼마나 개선하는지에 대한 측정이나 비교는 밝히지 않는다. 라샹스의 설명은 개인 프로젝트 사례와 평가에 근거하며, 다른 저장소나 작업에서도 같은 효과가 있는지는 제시하지 않는다.