AI가 작성한 '이유'를 사람의 판단으로 남기지 않다: 판단 기록과 코드 주석으로 의도 부채 줄이기
요약
본 글은 AI가 생성한 코드 주석이나 문서에 남겨진 의도(Intent Debt)를 관리하는 방법을 제시합니다. 특히, 판단 기록(ADR)을 작성할 때 '무엇이 이유인지'뿐만 아니라 '누구의 판단인지'를 분리하여 기록하는 시스템과 운영 현황을 소개합니다.
핵심 포인트
- 판단 기록은 '권장 이유(AI)'와 '근거(사람)'로 이원화해야 합니다.
- AI가 권장한 내용은 남기되, 근거란에는 오직 사람의 판단만 명시합니다.
- 코드 주석에는 ID와 코드를 읽는 데 필요한 짧고 간결한 '왜'만을 남깁니다.
최근 t-wada 님의 강연 자료가 공개되었습니다.
기술적 부채, 인지 부채, 그리고 의도 부채(Intent Debt) 세 가지를 정리한 자료이며, 14번째 장에 다음과 같이 쓰여 있습니다.
AI가 생성한 코드 주석이나 문서에 남은 의도의 상당 부분은 AI가 그럴듯하게 빈틈을 채운 결과물이며, 사람의 판단과 구별하기 어렵습니다.
저는 현재 5명의 팀으로 Claude Code를 전제로 한 개발 기반을 만들고 있습니다.
이 문장은 기반을 구축할 때 제가 가장 신경 썼던 문제 그 자체였습니다.
판단 기록(ADR: Architecture Decision Record)을 AI와 함께 작성하면, 기록은 남습니다.
다만, 남아 있는 '이유' 중 어느 것이 사람의 판단이고 어느 것이 AI의 작문인지 나중에 읽어도 구별할 수 없습니다.
본 기사에서는 그 구별을 위해 넣은 시스템과 운영 현황을 소개합니다.
TL;DR
판단 기록은 '무엇이 이유인가'만 남기는 것만으로는 부족합니다.
'누구의 이유인가'를 분리하여 남겨야 비로소 의도 부채에 대한 대책이 됩니다.
이 기사의 핵심 포인트
- 판단 기록의 이유란을 '권장 이유(AI)'와 '근거(사람)' 두 가지로 분리합니다.
- AI가 권장의 확신도를 (strong / flat)으로 신고하게 하고, flat일 경우 사람이 선택하면 이유를 물어 원문을 그대로 남깁니다.
- 판단 이유는 판단 기록에 작성하고, 코드 주석에는 ID와 코드를 읽는 데 필요한 짧은 '왜'만 남깁니다.
전제: 어떤 팀이 무엇을 만들고 있는가
팀은 PMO, PM, DS, SA(시스템 아키텍트), EN(엔지니어) 5명으로 구성되어 있으며, 저는 SA를 담당하고 있습니다.
만드는 것은 공개 전 신규 서비스로, 데스크톱 앱과 백엔드로 구성되어 있습니다(내용은 비공개).
PoC를 마치고 본 개발에 들어가는 타이밍에 모노레포(monorepo)를 새로 만들었습니다.
AI 에이전트는 Claude Code로 통일하고, 사양 주도 개발(SDD: Specification Driven Development)의 툴로서 spec-kit을 도입했습니다.
리포지토리에서 .claude/ 폴더를 관리하며, hooks와 skills, CI를 통해 사람과 AI 모두 동일한 절차를 따르도록 하고 있습니다.
SDD 운영이나 hooks로 Claude Code 편집을 막는 시스템은 내용이 길어 다른 기사로 분리하겠습니다.
본 기사에서는 판단 기록과 코드 주석에 초점을 맞춥니다.
의도 부채는 '누구의 이유인지 알 수 없을 때' 깊어진다
기반을 만들 때, 팀의 전략 기록에 의도 부채를 다음과 같이 정의했습니다.
판단의 근거가 나중에 추적할 수 없는 것. 게다가 AI의 '의도 같은 것'이 판단으로 남아 미래의 판단을 흔드는 것입니다.
전반부는 예전부터 있던 문제입니다.
베테랑이 퇴사하면 판단 이유도 함께 사라집니다.
AI로 바뀐 것은 모수(母數)입니다.
한 사람이 AI와 하루에 내리는 판단의 수는 이전과는 자릿수가 다릅니다.
후반부는 AI 시대에 고유한 문제입니다.
'왜 이렇게 했는지'를 AI에게 쓰게 하면, 그럴듯한 이유가 반드시 나옵니다.
Addy Osmani도
판단 기록의 이유를 AI와 사람으로 분리하다
판단 기록 템플릿은 이렇습니다.
### DEC-NNN-kk: [제목]
- 날짜: YYYY-MM-DD / 결정자: [사람]
- 선택지: A [..] / B [..] / C [..]
...
핵심은 '권장 이유(AI)'와 '근거(사람)'의 두 줄입니다.
AI의 권장 이유는 지우지 않습니다. 조사한 결과로서 가치가 있기 때문입니다.
다만 근거란에는 넣을 수 없습니다.
근거란에 쓸 수 있는 것은 오직 사람의 말뿐이며, 사람이 이유를 말하지 않았을 때는 '권장에 따름(이유 없음)'이라고 적습니다.
빈칸으로 두지 않습니다.
다만, 사람이 AI가 작성한 문장을 그대로 답안에 붙여 넣으면 근거란에서는 구별할 수 없습니다.
이 칸이 보장하는 것은 '사람이 썼다'는 것이 아니라, 'AI가 대필하지 않는 절차를 거쳤다'는 것까지입니다.
자리(위치)는 두 군데가 있습니다.
하나의 기능에 국한된 판단은 해당 기능의 spec(specs/NNN-xxx/spec.md)에 있는 '판단 기록' 장에 DEC-NNN-kk ID로 작성합니다.
여러 기능에 걸친 판단은 docs/decisions/에 1판단당 1파일로 두고, DEC-G-NNNN ID를 부여합니다.
실제 기록을 1건, 내용을 흐리게(모호하게) 넣습니다.
### DEC-001-01: 가져올 코드의 패키지 이름을 새 이름으로 변경하기
- 날짜: 2026-10-01 / 결정자: 필자
- 선택지: A 가져올 때 새 이름으로 변경 / B 그대로 두기
...
이 기록을 통해, 이름을 바꾼 이유는 AI가 제시한 것이고 사람은 특별한 이유 없이 권장에 따랐다는 것을 읽어낼 수 있습니다.
반년 후에 이 이름을 또 바꾸고 싶어진 사람은 당시 팀의 고집을 신경 쓰지 않고 변경할 수 있습니다.
만약 이유란이 하나였다면, AI의 권장 이유가 그대로 '결정한 이유'로 읽혔을 것입니다.
AI에게 확신도를 신고하게 하고, flat(보통)일 경우 '왜'를 묻기
칸을 분리해도 사람이 이유를 말하는 장면이 없으면 근거란은 채워지지 않습니다.
그래서 선택지가 나오면 반드시 통과시키는 /decide라는 skill을 만들고, Claude Code가 자동으로 작동하도록 했습니다.
절차는 4단계입니다.
- 조사 후 선택지를 제시한다 (기존 코드의 관습, spec의 제약, 요구사항, 라이브러리의 실태)
- 권장을 맨 앞에 두고 확신도를 스스로 신고한다
- flat(보통)일 경우, 사람이 고른 후에 '왜 그 선택을 했나요?'라고 묻는다
- 판단 기록에 작성하고, 코드에는 ID만 넣는다
확신도는 2단계입니다.
- strong: 권장에 강한 자신감이 있거나 다른 안거 강한 부정 근거가 있다. 반드시 권장 이유를 작성한다
- flat: 어느 것이나 좋다, 취향의 문제, 차이는 있지만 경미하다. 질문문 맨 앞에 '【フラット】'라고 붙이고, '차이는 경미합니다'라고 솔직하게 쓴다
flat을 도입한 것은 AI에게 '강한 근거는 없다'고 말하게 하기 위함입니다.
어떤 선택지에도 AI는 그럴듯한 권장 이유를 붙일 수 있습니다.
차이가 경미한 선택이라도, 강한 어조의 이유가 붙어 있으면 사람은 '그런가 보다' 하고 납득해 버립니다.
flat이라고 신고하게 하면, 적어도 '이 권장 이유는 강하지 않다'는 것이 기록으로 남습니다.
flat 선택일 때 이유를 물을 때는 선택지를 2개로만 합니다.
- 이유 작성 (자유 입력)
- 특별한 이유 없음 (권장에 따름 / 직감)
strong일 때는 묻지 않습니다.
사람이 권장대로 골랐다면 근거는 '권장에 따름', 다른 안을 골랐다면 이유를 묻습니다.
모든 판단에서 이유를 물으면, 대답하는 쪽이 지쳐서 '이유 없음'만 누르게 될 것이기 때문입니다.
skill의 '하지 않을 것(やらないこと)'에는 다음 3줄을 작성했습니다.
## 하지 않을 것
- 선택지를 내놓기 전에 구현을 진행하는 것
- 사람의 근거를 요약/言い換え/補完하는 것 (원문을 그대로)
...
가장 중요한 것은 2번째 줄입니다.
사람의 대답이 '데모에서 끝까지 동선을 보여주고 싶어서' 같은 짧은 한마디라도, AI는 그것을 다듬지 않습니다.
다듬는 순간, 그것은 AI의 문장이 되기 때문입니다.
권장과 함께 선택지를 AI가 내보내게 하는 고안은 이미 널리 알려져 있습니다.
grill-me skill 소개 기사나 logrus의 '선택지+권장도+이유' 글이 그렇습니다.
다만, 둘 다 사람이 왜 그것을 골랐는지는 기록하지 않습니다.
t-wada 님의 자료 23페이지에도 'AI가 선택지를 만들고 사람이 고르기만 해서는 이해가 자라나기 어렵다.'라고 있습니다.
flat일 때만 이유를 묻는 것은, 사람에게 생각하게 하는 과정을 부담되지 않는 범위에서 하나 추가하기 위함입니다.
/decide를 자동 실행시키는 설정과 그 한계
자동으로 실행시키기 위한 설정은 두 군데가 있습니다.
첫 번째는 skill의 frontmatter입니다 (description은 일부 생략했습니다).
---
name: "decide"
description: "작업 중에 설계・구현・사양상의 선택지가 발생하면 반드시 사용한다. 조사→선택지(권장 포함)→사람의 선택→근거 기록까지 진행하여, 의도 부채(AI의 의도가 사람의 판단으로 남는 것)와 인지 부채(사람이 생각하지 않고 진행하는 것)를 방지한다"
...
disable-model-invocation: false로 Claude가 자신의 판단으로 실행할 수 있고, user-invocable: true로 사람이 /decide라고 입력해도 실행할 수 있습니다.
본문의 '사용 타이밍'에는 나중에 '왜'를 물어볼 만한 선택(방식, 라이브러리, 데이터 구조, API 형태, 명명)이나 근거가 필요한 값(타임아웃, 재시도 횟수, 임계값), 사양의 모호함을 해석으로 채우는 장면을 언급했습니다.
포매터의 기본값이나 오탈자 수정과 같은 자명한 것은 대상에서 제외하고, 망설여지면 사용하라는 것입니다.
두 번째는 CLAUDE.md입니다.
'선택지가 발생하면 본문에 직접 쓰지 말고 /decide를 거친다(자동 실행해도 좋다)'라고 적혀 있습니다.
그럼에도 불구하고, 매번 실행이 보장되는 것은 아닙니다.
Claude Code는 description을 단서로 관련성이 있을 때 skill을 불러옵니다.
공식 문서에도 'skill이 실행되지 않을 때'의 대처법이 나와 있으며, 매번 반드시 지키게 하고 싶은 규칙은 hook으로 옮기도록 권장하고 있습니다.
/decide가 실행되지 않은 판단은 판단 기록에 남지 않으며, 늘어나는 DEC ID도 없으므로, 다음에 소개할 CI도 알아차릴 수 없습니다.
현재로서는 이 누락을 포착할 수 있는 것은 리뷰뿐입니다.
PR의 '판단' 장은 사람이 쓰고, CI는 그 줄이 있는지만 본다
판단 기록은 spec 안에 있기 때문에, 리뷰에서 건너뛰기 쉽습니다.
그래서 PR 템플릿에 '## 판단' 장을 만들고, 해당 PR에서 늘어난 판단을 사람이 한 줄씩 쓰기로 했습니다.
## 판단
<!--
이 PR에서 늘어난 판단 기록을 **사람이** 한 줄씩 쓴다.
...
CI는 차이점(diff)으로 새로 늘어난 DEC의 제목을 포착하고, 그 ID의 줄이 '## 판단' 장에 있는지 여부만 확인합니다.
표준 라이브러리만을 사용한 Python입니다.
DEC_ID = r"DEC-(?:–⁽–⁾|G-–⁾)"
HEADING = re.compile(rf"^#{{1,3}} ({DEC_ID}):")
LINE = re.compile(rf"^(?:- )?({DEC_ID})\s+[—-]\s+\S")
...
첫 버전은 PR 본문 전체에서 ID를 찾았습니다.
이렇게 하면, 템플릿의 HTML 주석에 들어있는 예시 ID나, '## 개요'에 ID만 적어놓은 PR도 통과해 버립니다.
글을 쓰다가 리뷰를 받고 깨달아, HTML 주석을 제외하고 '## 판단' 장에 있는 DEC-… — 한 줄 형태의 줄만 세도록 수정했습니다.
한 줄의 내용이 사람의 말인지 여부는 검사하지 않습니다.
'사람이 썼다'는 것을 기계로 증명할 방법이 없기 때문입니다.
CI에서 LLM에게 PR을 읽게 하는 방안도 생각했지만, PR별 과금과 대기 시간이 이 규모에 맞지 않아 채택하지 않았습니다.
이 한 줄을 AI가 쓰도록 해서 끝내는 사람은 시스템으로는 막을 수 없습니다.
시스템으로 막는 것은 '실수로 빼먹는' 정도까지로 하고, 일부러 우회하는 사람은 리뷰에서 잡아내기로 했습니다.
판단의 이유는 판단 기록으로. 코멘트에는 ID와 짧은 '왜'만
판단 기록을 정리하고 나니, 다음으로 신경 쓰이는 것이 코드 주석입니다.
코드를 AI에게 쓰게 하면, 주석에도 이유를 쓰기 시작합니다.
게다가 길게 씁니다.
주석 역시 또 다른 AI의 '의도 같은 것'이 놓일 장소가 됩니다.
제 생각에는 코드는 코드, 문서는 문서입니다.
사용 설명서가 붙어 있는 청소기의 버튼에, 그 버튼이 무엇이고 누르면 무슨 일이 일어나는지 스티커로 덕지덕지 붙이는 사람은 없습니다.
주석에 긴 설명을 쓰는 것은 그것과 같습니다.
길게 쓰고 싶다면 문서(document)에 적고, 주석에는 참조만 남기면 충분합니다.
규칙은 CLAUDE.md에 다음과 같이 쓰여 있습니다 (발췌).
## 코드 주석
주석에 쓸 것은 '왜'뿐입니다. '무엇을 하는지'는 코드가, '어떻게 사용하는지'는 spec / docs가 설명합니다.
써도 되는 것:
...
개선한 부분은 '써도 되는 것'의 범위를 좁게 나열했다는 점입니다.
함수의 doc comment에 한해서만 개요를 써도 된다고 했습니다.
하지만 AI는 '써도 된다'고 하면 필요 이상으로 많이 적습니다.
그래서 개요는 1줄, 최대 3줄로 숫자로 제한했습니다.
망설여질 때의 판단 기준은 '이 파일을 삭제해도 남아 있어야 할 정보인가'입니다.
남아 있어야 할 정보라면, 그것은 코드가 아니라 spec에 적습니다.
주석에 쓸 '왜'는 2가지 종류로 나누어 처리하고 있습니다.
하나는 해당 줄을 읽는 사람이 그 자리에서 알아야 하는 국소적인 이유입니다.
제약이나 회피책이 여기에 해당하며, 3줄까지는 주석에 적습니다.
다른 하나는 여러 안 중 1개를 선택한 판단의 이유입니다.
이것은 주석에 쓰지 않고 판단 기록(judgment record)에 작성하고, 코드에는 ID만 배치합니다.
// DEC-012-03: 재시도는 3회까지
const MAX_RETRY = 3;
나누는 이유는 판단 기록에는 AI의 추천 이유와 사람의 근거를 나누어 적을 칸이 있고, 주석에는 없기 때문입니다.
판단의 이유를 주석에 쓰면, 그것이 AI의 추천이었는지 사람의 판단이었는지 읽는 사람이 구분할 수 없습니다.
규정만으로는 옮겨온 코드의 주석은 줄지 않는다
UZU 기술 블로그의 'Claude가 작성한 긴 주석은 Claude 자신에게 도움이 되지 않았다'는 CLAUDE.md에 '비자명한 WHY만 적는다'고 쓴 후의 주석을 측정했습니다.
주석 비율은 21.1%에서 8.8%로 떨어졌습니다.
반면, 4줄 이상의 주석 블록은 52개에서 50개로 거의 줄지 않았습니다.
기사에서는 초반의 18줄 블록을 한 줄씩 확인하며 어느 줄도 코드로부터 복원할 수 없는 정보였기 때문에 이 규칙으로는 단 한 줄도 깎을 수 없다고 분석했습니다.
UZU의 기사는 이러한 현행 WHY를 주석에 직접 적는 입장을 취하고 있습니다.
태스크 ID도 코드에 쓰지 않고, 필요한 내용을 주석 본문에 쓰는 것으로 되어 있습니다.
코드에 판단 기록 ID를 배치하는 저희의 방침과는 여기가 반대입니다.
차이점은 저희의 ID가 가리키는 곳이 같은 리포지토리 내 spec 안에 있고, AI와 사람의 칸을 나눈 기록이라는 점입니다.
저희 프로젝트에도 비슷한 상황이 있었습니다.
PoC 코드는 주로 AI가 규정 없이 작성한 것이었습니다.
본 개발 리포지토리를 옮긴 후에도 주석 양은 별로 변하지 않았습니다.
규정은 새로 쓰는 코드에는 적용되지만, 옮겨온 코드를 다시 읽어주지는 않습니다.
그래서 옮겨온 코드(앱 측 98개 파일)에 규정에 맞춰 정리하는 작업을 한 번만 명시적으로 진행했습니다.
지시는 '이 코드는 본 개발의 사상을 따르지 않았으므로, 사상에 맞게 완전히 클린하게 해달라' 정도였습니다.
| 시점 | 주석 줄 수 | 비율 | 4줄 이상 블록 | 최장 블록 |
|---|---|---|---|---|
| PoC (AI가 규정 없이 작성) | 1,433 | 9.0% | 53 | 29행 |
| ... | ||||
| 4줄 이상에서 남은 3개 중 2개는 규정 대상이 아닌 빌드용 스크립트 사용법 설명입니다. |
남은 1개는 본문 2줄의 doc comment였습니다.
코드베이스가 다르기 때문에 UZU의 수치와 직접 비교할 수는 없지만, 저희 코드에서는 4줄 이상의 블록이 거의 사라졌습니다.
'3줄을 넘으면 spec로'라는 상한과 이유의 배치 장소(판단 기록)를 미리 마련해 두었던 것이 효과적이었다고 생각합니다.
정리 전후 예시를 하나 첨부합니다.
로그 출력 모듈의 일부입니다 (이름 일부는 가렸습니다).
// before (PoC)
// 앱 전체의 로그 관리.
// - electron main의 console.*을 패치하여 파일에도 쓰기
...
// after
// threshold는 파일 출력에만 적용 (콘솔은 개발 용도이므로 항상 출력)
const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
...
맨 앞의 '이 모듈이 무엇을 하는가' 설명은 코드와 docs가 말해주기 때문에 삭제되었습니다.
로그 레벨의 '왜(Why)'는 한 줄로 축소되어 남았고, '날짜가 바뀌었는지 첫 실행인지 →' 같은 번역 주석은 사라졌습니다.
하지만 이 정리 과정에서 손실된 정보도 있습니다.
다른 모듈에서는 '이 방식으로 해결되지 않는 경우는 향후 대응으로 한다'는 전망이 설명 단락 전체가 사라져 있었습니다.
규약에 따르면, 이것은 재검토 조건부로 spec(명세서)로 옮겨야 할 내용이었습니다.
줄이는 것과 옮기는 것은 별개의 작업이며, 이번에는 줄이는 쪽만 진행했습니다.
AI가 정리하게 하자 원문에 없는 이유가 섞였다
정리는 Claude Code에 맡기고, 5개의 서브 에이전트로 병렬 진행했습니다.
'주석 외에는 변경하지 않았다'는 것은 TypeScript의 파서(parser)로 주석을 제외한 토큰열을 정리 전과 비교하여 확인했습니다.
모든 파일에서 일치했고, 타입 체크와 lint 결과도 변하지 않았습니다.
그럼에도 불구하고, 취합 담당 에이전트가 차이점을 다시 읽어보니 오류가 3건 발견되었습니다.
- 값 변환 처리 부분에 'X를 Y로 변환한다'라고만 쓰여 있던 주석을, '사양상의 범위에 맞추기 위해'라고 수정했습니다. 원문에 없는 이유였고, 다른 파일의 타입 정의에 있는 값 영역과도 충돌했습니다.
- PoC(Proof of Concept) 시점에서는 정확했던 '표시를 전환하면 특정 UI 요소가 다시 만들어진다'는 설명을 그대로 남겨두었습니다. 현재 코드에서는 그 요소가 하나로 통합되어 있어 이 설명은 성립되지 않습니다.
- 순수한
#3
을 PoC 리포지토리의 #3으로 해석하여 참조를 수정했습니다. 실제 해당 번호는 무관한 PR(Pull Request)이었습니다.
1건째는, 이 글에서 다룬 의도 부채 그 자체입니다.
주석을 짧게 다시 쓰는 과정에서 AI가 원문에 없는 '왜'를 추가했습니다.
나중에 읽은 사람에게는 원래 작성자가 쓴 이유로만 보일 것입니다.
토큰열 비교는 '주석 외에는 변경하지 않았다'는 것을 보장해주지만, 주석 내용 자체가 올바른지는 알 수 없습니다.
수정된 부분을 누군가 읽는 과정은 이런 종류의 작업에서도 생략할 수 없었습니다.
판단 기록은 6건. 모두 권장대로였고, 사람의 이유가 남은 것은 1건
시스템을 도입한 것이 2026-09-18이고, 첫 기능에 착수한 것이 10-01입니다.
거기부터 일주일 만에 판단 기록이 6건 쌓였습니다.
| 판단 (요약) | 확신 | 채택 | 근거 (사람) |
|---|---|---|---|
| 포함할 코드의 패키지 이름을 변경한다 | flat | 권장 | 권장에 따름 (이유 없음) |
| ... | |||
| 6건 모두에서, 사람은 AI의 권장을 그대로 채택했습니다. |
flat 중 4건에 대한 3건은 '이유 없음'입니다.
사람이 자신의 말로 이유를 말한 것은 모크(mock) 동작을 결정한 1건뿐이었습니다.
실패처럼 보일지도 모릅니다.
그럼에도 저는, 이것을 시스템이 처음 보여준 성과라고 보고 있습니다.
이유란이 1개였다면, 이 6건에는 AI의 권장 이유가 '결정한 이유'로 나열되어 있었을 것입니다.
읽은 사람은, 6건 모두 사람이 생각해서 결정했다고 받아들였을 겁니다.
지금은, 그중 3건은 아무도 이유 없이 결정했다는 것이 기록에서 읽힙니다.
나중에 바꾸고 싶어졌을 때, 어떤 판단이라면 가볍게 뒤집어도 되는지 알 수 있습니다.
반면, 사람에게 생각하게 하는 것까지는 도달하지 못했습니다.
이유를 물어봐도, '특별한 이유 없음'을 선택하면 먼저 진행할 수 있기 때문입니다.
여기부터는 가설입니다.
flat의 선택지에서도 권장을 맨 앞에 두고 있기 때문에, 사람은 그것에 편승하기 쉬워지고 있는 것이 아닐까 생각합니다.
차이가 미미하다고 AI 스스로 말하는 선택지에 권장을 붙이면, 그것은 사실상의 기본값(default)이 됩니다.
다음으로는, flat의 경우에는 권장 없이 선택지를 나열하는 운영을 시도할 계획입니다.
6건만으로는 어느 쪽이라고 단정할 수 없으므로, 건수가 쌓인 후에 비교해 보겠습니다.
기록과는 다른 장소에서 사람의 말이 나온 경우도 있었습니다.
소재 파일의 위치를 결정한 1건은, 판단 기록에서는 '권장에 따름'이었습니다.
그런데 멤버가 작성한 PR의 '## 판단' 장에는 이유가 자신의 말로 쓰여 있었습니다.
판단 직후보다, PR을 제출할 때가 언어화하기 더 쉬할지도 모릅니다.
이 또한 단 한 건의 관찰입니다.
요약
| 메커니즘 | 방지하는 것 | 강제하는 방법 | 한계 |
|---|---|---|---|
| 이유란을 '권장 이유(AI)'와 '근거(사람)'로 분리하기 | AI의 이유가 사람의 판단으로 남는 것 | 템플릿과 /decide skill | '권장에 따르기'로 진행하면 근거는 빈 상태로 남는다. 사람이 AI 문장을 붙여도 구별할 수 없다 |
/decide의 자동 실행 | 판단이 기록되지 않고 지나가는 것 | skill의 description과 CLAUDE.md | 작동하지 않으면, 기록도 CI 검사도 일어나지 않는다 |
| 확신도 strong / flat 신고 | 약한 권장이 강하게 보이는 것 | skill의 절차 | 신고의 정확성은 AI에 맡긴다 |
| flat일 경우 이유를 묻고 원문에 남기기 | 사람이 생각하지 않고 결정한 것이 보여지는 것 | skill의 절차 (대필・요약 금지) | '이유 없음'으로 통과할 수 있다 |
| ... | |||
| 의도 부채는 AI 이전부터 존재하는 부채이므로, 0으로는 만들 수 없습니다. |
그럼에도 불구하고 '누구의 이유인지'를 나누어 적기만 해도, 기록을 읽는 방식이 바뀝니다.
6건 모두 권장대로였다는 사실이 눈에 보이게 된 것도, 칸을 나눈 덕분이었습니다.
맺음말
본문에서 소개한 /decide skill,
판단 기록 템플릿, '## 판단' 장을 검사하는 CI는 아래 리포지토리에 모아두었습니다.
꼭 사용해 보시고 의견 주시면 큰 힘이 됩니다.
참고 문헌
- 부채의 메타포와 2026년 / Debt Metaphor in Agentic Engineering Age 202609 Edition (t-wada, 기술적 부채에 직면하는 Conference 2026, 2026-09-17)
- The Intent Debt (Addy Osmani, 2026-06-05)
- From Technical Debt to Cognitive and Intent Debt: Rethinking Software Health in the Age of AI (Margaret-Anne Storey, arXiv, 2026-03-23)
- Claude가 작성하는 긴 코멘트는 Claude 자신에게 도움이 되지 않았다 (UZU 기술 블로그, 2026-08-05)
- 규칙이 아닌 skill에 지시를 적음으로써 Claude의 코멘트를 줄일 수 있었다 (UZU 기술 블로그, 2026-09-03)
- AI와의 대화 이력을 자산으로 삼기. DDR(Design Decision Record) 자동 기록 메커니즘 (소프트뱅크, 2026-08-21)
- AI의 질문을 '선택지 + 권장도 + 이유'로 하니, 의사결정의 질과 속도가 압도적으로 올랐다 (로그라스, 2025-11-12)
- grill-me skill이 매우 좋아서 전파하고 싶다 (2026-04-09)
토론

AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기