코드에는 결과만 남고,
이유는 사람에게 남는다.

GitHubGitHub Docs공식 문서영어

GitHub Copilot이 읽는 저장소 수준 지시 파일을 정의한 공식 문서다(2026-09 열람 기준 현행 문서). 저장소 전체 요청에 적용되는 `.github/copilot-instructions.md`, `applyTo` 프런트매터로 경로를 한정하는 `.github/instructions/NAME.instructions.md`, 그리고 저장소 어디에나 둘 수 있는 AGENTS.md와 루트의 CLAUDE.md·GEMINI.md를 다루며, 중첩된 AGENTS.md는 디렉터리 트리에서 가장 가까운 것이 우선한다. 개인·저장소·조직 지시가 함께 쓰일 때 우선순위는 개인 > 저장소 > 조직이다. 기능별 지원 범위는 별도 참조 문서(custom-instructions-support)에 표로 정리되어 있다.

“If the path you specify matches a file that Copilot is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used.”

GitHub PR 리뷰 봇과 클라우드 에이전트까지 같은 의도 파일을 읽게 하려면 어떤 파일명을 어디에 둬야 하는지, 그리고 여러 지시 파일이 어떻게 겹치고 우선되는지를 정하는 벤더 기준 문서다.

저장소 지시 파일

lv2devvelog블로그한국어

모호한 자율성이 프로젝트 방향성 훼손으로 이어진다는 문제의식에서, 프로젝트 루트의 `.ai/` 디렉터리에 `system_prompt.md`(마스터 통제 지시문)와 `memory/plan.md`·`context.md`(아키텍처 결정·프로젝트 트리)·`checklist.md`를 모으는 구조를 제안한 한국어 실무 글이다. `CLAUDE.md`·`GEMINI.md`·`AGENTS.md`를 모두 `.ai/system_prompt.md`로의 심볼릭 링크로 만들어 도구가 달라도 하나의 규칙을 보게 한다. Karpathy의 네 원칙(Think Before Coding, Simplicity First, Surgical Changes, Verifiable Goals)을 지시문에 넣고, 메모리 파일 확인 → plan.md 작성 → 사용자 승인 → 최소 변경과 스크립트 검증 순서로 작업하게 한다.

“Claude, Gemini, Junie 등 사용하는 도구가 달라도, 심볼릭 링크(Symbolic Link)를 통해 단 하나의 통제 규칙(`.ai/system_prompt.md`)을 바라보게 만들어 프로젝트 전체의 AI 룰셋을 완벽하게 동기화합니다.”

Claude Code·Gemini CLI·Junie 등 여러 에이전트를 함께 쓸 때, 규칙과 아키텍처 결정 기록을 한 디렉터리에 두고 심볼릭 링크로 도구별 지시 파일에 연결하는 구체적 SSOT 구조를 한국어로 보여 준다.

저장소 지시 파일에이전트 메모리강제 장치·기여 정책

김경윤 (토스뱅크 ML Engineer)Toss Tech (토스 기술 블로그)블로그한국어

코딩 에이전트가 팀 컨벤션과 아키텍처 패턴을 놓치는 문제를 다룬다. Stylepack 플러그인은 파일 작성 직후와 작업 완료 직전의 두 훅에서 중앙 저장소의 규칙(트리거 조건과 주입할 컨텍스트)을 매칭해 에이전트에 지침을 주입한다. 세션 시작 때 준 지시는 'Lost in the Middle' 현상 때문에 뒤로 갈수록 희미해지므로, 코드가 쓰이는 순간에 피드백을 주는 방식을 택했다. 규칙이 발동할 때마다 로그를 남겨 오탐과 미탐을 점검한다.

“방금 작성한 코드에 바로 코멘트를 남길 수 있다는 것이에요. '아까 세션 시작에 말했잖아'가 아니라, '방금 네가 쓴 이 줄이 문제야'라고 말할 수 있는 거죠.”

세션 시작에 규칙을 한 번 전달하는 방식의 한계를 짚고, 팀 규칙을 언제 주입할지 설계한 국내 사례다. 팀의 의도를 에이전트가 작업하는 시점에 전달해 변경이 프로젝트 방향에서 벗어나는 것을 줄이는 접근으로 쓸 수 있다.

저장소 지시 파일강제 장치·기여 정책측정과 실증

AnthropicClaude Code Docs (code.claude.com); 원출처 Anthropic Engineering 블로그 "Claude Code: Best practices for agentic coding" (2025-04, 현재 이 문서로 308 리다이렉트)공식 문서영어

Anthropic이 Claude Code 사용법을 정리한 공식 실천 가이드로, 원래 2025년 4월 Anthropic Engineering 블로그에 실렸던 글이 현재는 code.claude.com 문서로 흡수되어 옛 URL이 308 영구 리다이렉트된다(2026-09 열람 기준 현행 판을 인용). CLAUDE.md를 "코드만으로는 유추할 수 없는 영속 컨텍스트"로 규정하고, 포함할 것(추측할 수 없는 Bash 명령, 기본값과 다른 스타일 규칙, 프로젝트 고유의 아키텍처 결정, 비자명한 함정)과 제외할 것(코드를 읽으면 알 수 있는 것, 파일별 설명, 자주 바뀌는 정보, 긴 설명)을 표로 대비한다. 각 줄마다 "이 줄을 지우면 Claude가 실수하는가"를 묻고 아니면 삭제하라고 하며, 비대한 CLAUDE.md는 정작 중요한 지시를 무시하게 만든다고 경고한다. 프롬프트 예시로 "ExecutionFactory의 git 히스토리를 훑어 API가 어떻게 이렇게 됐는지 요약하라"처럼 근거의 출처를 지목하라는 항목도 포함한다.

“Keep it concise. For each line, ask: "Would removing this cause Claude to make mistakes?" If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!”

의도 부채를 줄이려고 CLAUDE.md에 모든 것을 적는 함정을 피하고, "코드에서 유추 불가능한 결정과 함정"만 남기는 선별 기준과 코드처럼 리뷰·정리하는 유지보수 루틴을 제공한다.

저장소 지시 파일강제 장치·기여 정책

OpenAIOpenAI Codex Docs (learn.chatgpt.com)공식 문서영어

OpenAI Codex가 AGENTS.md를 어떻게 발견하고 병합하는지 규정한 공식 문서다. 전역 범위(`~/.codex/AGENTS.override.md`, 없으면 `~/.codex/AGENTS.md`)와 프로젝트 범위(프로젝트 루트, 보통 Git 루트에서 현재 작업 디렉터리까지 내려오며 각 디렉터리의 AGENTS.override.md → AGENTS.md → 대체 파일명 순으로 확인)를 모아 하나의 지시 체인으로 결합하고, 현재 디렉터리에 가까운 파일일수록 결합 프롬프트의 뒤에 오므로 앞선 지침을 덮어쓴다고 설명한다. 테스트·의존성 같은 작업 합의, 린트·문서화 같은 저장소 기대치, 코드 리뷰 규칙, 프로젝트 셋업 안내처럼 세션마다 반복하지 않아도 유지돼야 할 내용을 담는 곳으로 정의한다.

“Files closer to your current directory override earlier guidance because they appear later in the combined prompt.”

32 KiB 상한과 "가까운 파일이 이긴다"는 병합 규칙을 알아야 모노레포에서 패키지별 의도를 어느 디렉터리의 AGENTS.md에 적을지, 루트 파일을 얼마나 짧게 유지할지 설계할 수 있어 의도 부채 해소용 지시 파일 운영의 구체적 제약 조건을 제공한다.

저장소 지시 파일

Thibaud Gloaguen, Niels Mündler, Martin Vechev (ETH Zurich); Mark Müller, Veselin Raychev (LogicStar.ai)arXiv cs.SE (2026-02-12 v1, 2026-06-23 v2)논문영어

AGENTS.md·CLAUDE.md 같은 저장소 컨텍스트 파일이 실제로 코딩 에이전트의 과제 해결률을 올리는지 SWE-bench Lite(11개 인기 저장소 300개 과제, LLM 생성 파일)와 새로 만든 CTXbench(12개 틈새 저장소 138개 인스턴스, 개발자가 커밋한 파일)에서 Claude Code(Sonnet 4.5)·Codex(GPT-5.2, GPT-5.1 mini)·Qwen Code(Qwen3-30B-coder)로 검증한 연구다. 파일의 지시는 잘 따르지만 성공률은 전반적으로 오르지 않고 추론 비용만 평균 20% 이상 늘었으며, 벤더가 권하는 저장소 개요 섹션은 관련 파일을 더 빨리 찾게 하지 못했다. 컨텍스트 파일은 README에 없는 비표준 관행이나 비기능 요구사항만 담고 도입 전 엄격히 평가하라고 권고한다. 2026년 7월 Khatri의 독립 절제 연구(arXiv 2607.27250, 3개 저장소 17개 과제 288회 실행)도 정확도 개선을 확인하지 못해 같은 방향을 가리킨다.

“Surprisingly, we find that providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average.”

CLAUDE.md를 길고 자세하게 쓰면 에이전트가 좋아질 것이라는 통념을 반박하는 통제 실험이다. 코드베이스에서 이미 발견 가능한 개요를 되풀이하는 대신, 문서에 없는 결정·제약·관례처럼 실제로 의도 부채에 해당하는 내용만 담아야 한다는 근거로 쓸 수 있다.

저장소 지시 파일측정과 실증

AnthropicClaude Code Docs (code.claude.com)공식 문서영어

Claude Code가 세션 간 지식을 이어 가는 두 장치, 사용자가 쓰는 CLAUDE.md와 Claude가 스스로 쓰는 auto memory를 설명하는 공식 문서다(2026-09-11 열람 기준 현행 문서). CLAUDE.md는 관리 정책·사용자·프로젝트·로컬의 네 범위에 두고 파일시스템 루트부터 작업 디렉터리까지 연결(concatenate)되며, 하위 디렉터리 파일은 그 안의 파일을 읽을 때 지연 로드되고 `@path` import와 `.claude/rules/`의 `paths` 프런트매터로 경로별 규칙을 분리할 수 있다. 문서는 CLAUDE.md를 "그렇지 않으면 다시 설명해야 할 것을 적는 곳"으로 규정하고, Claude가 같은 실수를 두 번째 할 때·코드 리뷰가 이 코드베이스에서 알았어야 할 것을 잡을 때·지난 세션에 쳤던 정정을 또 칠 때·새 팀원도 같은 맥락이 필요할 때 기록하라고 한다. `/doctor`는 코드에서 유도 가능한 내용(디렉터리 구조·의존성 목록·아키텍처 개요)은 잘라내되 함정·근거(rationale)·도구 기본값과 다른 관례는 남기도록 제안한다는 점에서, 의도 부채를 "코드에서 유추할 수 없는 것"으로 정의하고 저장 위치를 지정하는 문서다.

“Treat CLAUDE.md as the place you write down what you'd otherwise re-explain.”

CLAUDE.md에 무엇을 넣고 무엇을 rules·skills·auto memory로 분리할지, 그리고 "왜"(rationale)를 어디에 남겨야 다음 세션의 에이전트가 실제로 읽는지에 대한 가장 구체적인 1차 규격이다. 도구 벤더가 "코드에서 유도할 수 없는 것"만 기록 대상으로 삼는 기준을 명문화한 사례로 인용할 수 있다.

저장소 지시 파일에이전트 메모리결정 기록(ADR)

Cognition (Devin / Windsurf)Devin Docs (docs.devin.ai)공식 문서영어

Windsurf에서 리브랜딩된 Devin Desktop의 Cascade 에이전트가 쓰는 두 종류의 영속 컨텍스트를 설명하는 공식 문서다(docs.windsurf.com의 옛 경로는 이 문서로 307 리다이렉트된다). Memories는 Cascade가 대화 중 자동 생성해 사용자 기기의 워크스페이스 단위로만 남고 저장소에 커밋되지 않으며, Rules는 사용자가 전역·워크스페이스·시스템 수준에서 직접 정의해 버전 관리와 팀 공유가 가능한 마크다운 파일이다. 워크스페이스 규칙은 `.devin/rules/*.md`(권장) 또는 `.windsurf/rules/*.md`(레거시)에 두고, 프런트매터로 Always On·Model Decision·Glob·Manual 네 활성화 방식 중 하나를 고른다.

“Memories generated in one workspace are not available in another, and they are not committed to your repository.”

규칙 파일의 글자 수 상한을 명시한 드문 공식 문서로, 의도 기록을 "매번 로드(Always On)"와 "관련 파일·판단 시에만 로드(Glob·Model Decision)"로 나누는 컨텍스트 예산 설계와, 개인 로컬 메모리와 팀 공유 규칙을 분리하는 설계의 참고가 된다.

저장소 지시 파일에이전트 메모리

Google (Gemini CLI)Gemini CLI Docs (geminicli.com)공식 문서영어

Gemini CLI의 컨텍스트 파일 GEMINI.md를 설명하는 공식 문서다(2026-06-18 최종 갱신, 2026-09 열람 기준 현행 문서). 전역(`~/.gemini/GEMINI.md`) → 워크스페이스 디렉터리와 그 상위 디렉터리 → 도구가 파일이나 디렉터리에 접근하는 시점에 해당 디렉터리와 조상(신뢰 루트까지)을 스캔하는 JIT(just-in-time) 로드의 계층 순서로 파일을 모아 연결한 뒤 매 프롬프트마다 모델에 보낸다. `@file.md` 구문으로 상대·절대 경로 파일을 import해 큰 파일을 모듈화할 수 있고, `/memory show`로 실제 결합된 컨텍스트를 확인하며 `/memory reload`로 재스캔한다.

“When a tool accesses a file or directory, the CLI automatically scans for `GEMINI.md` files in that directory and its ancestors up to a trusted root.”

JIT 로드와 `context.fileName` 설정 덕분에 AGENTS.md 하나를 SSOT로 두고 Gemini CLI도 같은 의도 문서를 읽게 하는 구성이 가능함을 공식 문서로 확인할 수 있다. 저장소 계층별로 의도를 분산 기록하고 필요 시점에 합쳐 읽는 설계 사례다.

저장소 지시 파일

Jeff Smith (Neoteny AI, ex-Meta/FAIR)QCon London 2026, AI Engineering track (2026-03-17)발표영어

코딩 모델은 수개월 전 오픈소스 코드 스냅샷으로 학습돼 사내 코드베이스나 최근에 작성된 코드를 본 적이 없다는 불일치를 다룬 강연이다. 여러 주요 오픈소스 프로젝트에서 PR의 AI 도구 언급은 2022~2025년 사이 50배 늘었지만 PR 수락률은 74.7%에서 66.2%로 떨어졌다는 데이터를 제시한다. 원인으로는 시니어 엔지니어의 머릿속과 커밋 히스토리 패턴에만 있는 저장소별 '불문율'(아키텍처 제약)을 꼽는다. 이 규칙을 드러내 AI 도구의 시스템 프롬프트와 리뷰 체크리스트에 넣고, 현재 도구가 핵심 제약을 지키는지 평가하는 실천 프레임워크를 제안한다.

“every repository has its own unwritten rules, architectural constraints that live in the heads of your senior engineers and in the patterns of your commit history”

AI 기여는 늘었는데 PR 거절도 늘어난 현상을 수치로 보여 주고, 그 원인을 문서화되지 않은 저장소별 의도와 제약에서 찾는다. 불문율을 명시해 에이전트가 쓸 수 있는 자리에 두는 것이 도구 문제보다 지식 관리 문제에 가깝다는 점을 짚는다.

저장소 지시 파일조직 지식 검색커밋 히스토리·변경 출처측정과 실증강제 장치·기여 정책

ClineCline Docs공식 문서영어

Cline의 규칙 파일 체계를 다룬 공식 문서다(2026-09 열람 기준 현행 문서). 프로젝트 루트의 `.clinerules/` 폴더 안 모든 `.md`·`.txt` 파일을 하나의 규칙 집합으로 합치고, 전역 규칙(macOS·Linux `~/Documents/Cline/Rules`, Windows `Documents\Cline\Rules`)과 충돌하면 워크스페이스 규칙이 우선한다. `.cursorrules`·`.windsurfrules`·AGENTS.md도 자동 감지해 Rules 패널에서 개별 토글할 수 있다. 작성 지침으로 모호한 표현 대신 구체적 관례(변수 camelCase, 클래스 PascalCase)를 적고, 규칙이 임의로 보일 때는 그 이유(why)를 함께 설명하며, 저장소에 이미 있는 코드 예시를 가리키고, 파일당 한 관심사만 다루라고 권한다.

“Include the why. When a rule might seem arbitrary, explain the reason. 'Don't modify files in /legacy (this code is scheduled for removal in Q2)' helps Cline make better decisions in edge cases.”

"규칙에 이유(why)를 적어라"와 "architecture.md에 구조적 결정을 두라"는 지침은 의도 부채를 규칙 파일 안에서 직접 다루는 가장 명시적인 벤더 권고 중 하나다.

저장소 지시 파일

Cursor (Anysphere)Cursor Docs공식 문서영어

Cursor의 프로젝트 규칙 체계를 설명하는 공식 문서다(2026-09 열람 기준 현행 문서). LLM은 완료 사이에 기억을 유지하지 않으므로 규칙이 프롬프트 수준에서 지속적이고 재사용 가능한 컨텍스트를 제공한다고 설명한다. `.cursor/rules/*.mdc` 파일은 프런트매터의 `description`·`globs`·`alwaysApply`에 따라 항상 적용, 에이전트가 설명을 보고 관련성 판단, 파일 패턴 일치 시 적용, `@rule` 수동 호출의 네 방식으로 컨텍스트에 들어간다. 프로젝트 루트와 하위 디렉터리의 AGENTS.md도 지원하며 중첩된 지시는 더 구체적인 것이 우선하는 계층 구조로 결합된다. 규칙을 500줄 이하로 유지하고 큰 규칙은 조합 가능한 여러 규칙으로 나누며 구체적 예시나 참조 파일을 제공하라고 권고한다.

“Large language models don't retain memory between completions. Rules provide persistent, reusable context at the prompt level.”

컴포넌트 디렉터리별로 "왜 이렇게 만들었는지"를 globs 규칙이나 하위 디렉터리 AGENTS.md로 묶어 관련 파일을 만질 때만 로드시키는 경로 한정 의도 기록 방식의 원형이다. 규칙 문서 자체가 LLM의 세션 간 기억 부재를 전제로 지속 컨텍스트를 제공한다고 명시해 의도 부채 대응의 도구 벤더 측 접근을 보여준다.

저장소 지시 파일

Aider (Paul Gauthier)aider.chat Docs공식 문서영어

터미널 AI 페어 프로그래밍 도구 Aider가 CONVENTIONS.md 같은 관례 파일을 채팅에 포함시켜 코드 생성을 프로젝트 표준(선호 라이브러리, 타입 힌트, 명명 규칙 등)에 맞추는 방법을 설명하는 공식 문서다(페이지에 날짜 없음, 2026-09 열람 기준 현행 문서). 파일을 `/read CONVENTIONS.md`나 `aider --read CONVENTIONS.md`로 올리면 읽기 전용으로 표시되어 수정 대상에서 제외되고 프롬프트 캐싱이 켜져 있으면 캐시되며, `.aider.conf.yml`의 `read:` 항목으로 항상 로드하게 할 수 있다. "requests 대신 httpx", "가능한 모든 곳에 타입 힌트" 두 줄짜리 예시로 파일 유무에 따라 생성 코드가 달라지는 것을 실제 대화 기록으로 보여 준다.

“It's best to load the conventions file with /read CONVENTIONS.md or aider --read CONVENTIONS.md. This way it is marked as read-only, and cached if prompt caching is enabled.”

가장 단순한 형태의 의도 파일이 어떻게 동작하는지 보여 주며, 읽기 전용·캐시 로드라는 발상은 다른 도구의 규칙 파일(CLAUDE.md, .cursor/rules 등) 설계에도 그대로 이어진다. 다만 코딩 스타일 관례에 한정되어 있어 결정의 이유나 버린 대안 같은 의도 부채의 핵심 정보는 다루지 않는다.

저장소 지시 파일

Birgitta Böckeler (Thoughtworks) / InfoQQCon London 2026 키노트 (InfoQ 게시 2026-04-08)발표영어

Thoughtworks의 Birgitta Böckeler가 AI 코딩 어시스턴트가 자율 에이전트로 넘어간 현황을 정리한 42분 키노트다. 스킬처럼 필요할 때만 불러오는 모듈형 컨텍스트로 에이전트에 줄 정보를 관리하는 방식을 설명하고, dependency-cruiser·ArchUnit 같은 구조 테스트와 에이전트용 힌트를 담은 린트 오류 메시지로 아키텍처 제약을 되먹임하는 방법을 소개한다. 하니스를 갖춘 OpenAI 팀도 엔트로피 증가와 드리프트를 겪어 에이전트가 계속 코드베이스를 정리하는 '가비지 컬렉션'을 돌렸다는 사례를 인용한다. 감독 수준은 오류 확률·영향·탐지 가능성의 조합으로 판단하라는 틀도 제시한다.

“They had entropy increasing and drift happening. They had what they called garbage collection, like agents continuously running against the codebase and cleaning up over time.”

dependency-cruiser 같은 구조 테스트로 아키텍처 의도를 에이전트가 읽을 수 있는 규칙과 오류 메시지로 바꾸는 방법을 보여 준다. 그렇게 해도 드리프트가 쌓인다는 한계도 함께 보여 준다.

저장소 지시 파일강제 장치·기여 정책이해 유지 실천

Ryan Lopopolo (OpenAI, Member of Technical Staff)OpenAI 엔지니어링 블로그 (공식 한국어 판)블로그한국어

OpenAI의 Ryan Lopopolo가 2026년 2월 11일에 쓴 글이다. 5개월 동안 사람이 코드를 한 줄도 직접 쓰지 않고 Codex로 약 100만 줄 규모의 내부 베타 제품을 만든 실험을 정리한다. 엔지니어 3명이 약 1,500개 PR을 열고 병합했고, 이후 팀은 7명으로 늘었다. 저장소에서는 약 100줄짜리 AGENTS.md를 목차로 두고 docs/ 디렉터리(설계 문서, 의사결정 로그가 붙은 실행 계획, 기술 부채 추적기)를 기록 시스템으로 삼는다. Slack이나 사람들의 머릿속에 있는 지식을 저장소로 옮기고, 린터·CI·doc-gardening 에이전트로 문서 신선도를 기계적으로 강제한다. 매주 금요일에 하던 수동 'AI 슬롭' 정리는 저장소에 인코딩한 '황금 원칙'과 백그라운드 정리 작업으로 대체했다.

“에이전트의 관점에서 보면 실행 중에 컨텍스트 내에서 액세스할 수 없는 것은 사실상 존재하지 않는 것입니다. Google Docs, 채팅 스레드 또는 사람들의 머릿속에 있는 지식은 시스템에서 접근할 수 없습니다.”

이 글은 의도 부채를 줄이려고 의도를 저장소에 모두 적고 기계로 강제하는 전략의 실제 사례다. 대화·문서·머릿속에 있던 지식을 버전 관리되는 아티팩트로 옮기는 구체적인 구조와, 그 전략의 운영 비용(주 20% 정리 작업, 문서 린터, doc-gardening 에이전트)을 함께 보여 준다. 그래서 팀이 사람의 이해에 기댈지, 외재화와 강제에 기댈지 정할 때 비교 기준이 된다.

저장소 지시 파일결정 기록(ADR)명세 주도 개발강제 장치·기여 정책

김건우 (한컴테크)한컴테크 (한글과컴퓨터 기술 블로그)블로그한국어

CLAUDE.md는 200줄 이하로 유지하고 WHAT(기술 스택·구조), WHY(각 부분의 목적), HOW(작업 방식)만 담으라고 권한다. 작업 중 결정 사항과 막힌 지점, 진행 상황은 AI가 decisions.md 같은 외부 파일에 기록하게 하고, 코드 조각 대신 @import로 파일 경로만 가리키게 하라고 제안한다. 코딩 에이전트에게는 긍정 지시보다 금지 제약이 효과적이며, LLM이 자동 생성한 컨텍스트는 SWE-bench Lite에서 오히려 성공률을 낮췄고 입력이 길수록 성능이 떨어진다(Context Rot)는 연구를 들어 사람이 선별한 최소 컨텍스트를 권한다.

“decisions.md 같은 파일을 두고 "작업 중 결정 사항이나 막힌 지점을 여기에 기록해"라고 지시해두면, 긴 세션에서도 길을 잃지 않습니다.”

CLAUDE.md 본문에는 WHY(목적)를 짧게 두고 결정 기록은 별도 파일로 떼어 내는 구체적 파일 구성을 한국어로 제시해, 의도를 에이전트가 찾을 수 있게 남기는 실무 템플릿으로 쓸 수 있다.

저장소 지시 파일결정 기록(ADR)에이전트 메모리

Worawalan Chatlatanagulchai, Hao Li, Yutaro Kashiwa, Brittany Reid, Kundjanasith Thonglek, Pattara Leelaprute, Arnon Rungsawang, Bundit Manaskasemsak, Bram Adams, Ahmed E. Hassan, Hajimu IidaarXiv cs.SE (v1 2025-11-17, v2 2026-08-09)논문영어

GitHub 저장소 1,925개에서 CLAUDE.md, AGENTS.md, copilot-instructions.md 2,303개를 수집해 구조·유지보수·내용을 분석한 최초의 대규모 실증 연구다. 근거 이론 방식으로 16개 지시 범주를 도출한 결과 테스트·구현 세부·아키텍처 같은 기능적 맥락이 압도적이고 보안·성능 같은 비기능 요구는 드물었으며, 파일은 읽기 어렵고 작은 추가가 잦은 '설정 코드'처럼 진화한다. 저자들은 개발자가 에이전트를 '돌아가게' 하는 지시는 많이 쓰지만 '잘 만들게' 하는 품질 가드레일은 거의 적지 않는다고 결론짓는다.

“these files are not static documentation but complex, difficult-to-read artifacts that evolve like configuration code through frequent, small additions.”

남들의 CLAUDE.md에 무엇이 들어 있고 무엇이 빠져 있는지(특히 보안·성능 같은 비기능 제약)를 수치로 보여 주어, 자기 팀의 컨텍스트 파일이 에이전트에 어떤 의도와 제약을 전달하지 못하고 있는지 점검하는 기준선이 된다.

저장소 지시 파일측정과 실증

Agent Skills project (originally developed by Anthropic)agentskills.io표준·규약영어

Agent Skills는 SKILL.md 파일이 든 폴더로 에이전트에 전문 지식과 작업 절차를 더하는 개방형 형식이다. SKILL.md에는 최소한 name과 description 메타데이터, 그리고 지시문이 들어간다. 절차 지식과 회사·팀·사용자별 맥락을 이식 가능하고 버전 관리되는 폴더로 묶어 두고, 에이전트는 필요할 때 이를 적재한다. 적재는 발견(이름·설명만) → 활성화(SKILL.md 전체) → 실행(필요한 스크립트·참조 파일)의 3단계 점진적 공개로 이뤄진다. Anthropic이 처음 개발해 개방 표준으로 공개했고, 여러 에이전트 제품이 채택했다.

“Skills solve this by packaging procedural knowledge and company-, team-, and user-specific context into portable, version-controlled folders that agents load on demand.”

팀의 반복 절차와 암묵지를 벤더 중립 형식으로 저장소에 커밋해 두면, 팀원이 어떤 에이전트를 쓰든 같은 절차 지식을 받게 된다. 사람 머릿속에만 있던 절차를 발견 가능한 산출물로 바꾸는 방법의 예다.

저장소 지시 파일조직 지식 검색강제 장치·기여 정책

Agent Skills project (originally developed by Anthropic)agentskills.io표준·규약영어

이 명세는 SKILL.md 형식을 정의한다. YAML frontmatter 필드(필수는 name·description, 선택은 license·compatibility·metadata·allowed-tools)와 디렉터리 관례(scripts/, references/, assets/), 점진적 공개 단계별 권장 크기, 검증 도구를 다룬다. description에는 스킬이 무엇을 하는지와 언제 쓰는지를 모두 적고, 에이전트가 관련 작업을 알아볼 수 있도록 구체적인 키워드를 넣으라고 권한다. 의도 부채 관점에서 보면, 에이전트가 지식을 찾아 쓰게 하는 인터페이스와 컨텍스트 예산을 형식 수준에서 규정한 문서다. 다만 skills-ref 검증은 frontmatter와 명명 규칙만 검사하고, 담긴 내용이 현재 코드와 맞는지는 다루지 않는다.

“Should describe both what the skill does and when to use it. Should include specific keywords that help agents identify relevant tasks”

팀 절차를 스킬로 옮길 때 이 지식이 언제 필요한지를 description에 적는 규칙과 크기 예산을 알면, 에이전트가 실제로 찾아 쓰는 지식 패키지를 설계할 수 있다.

저장소 지시 파일조직 지식 검색

Agentic AI Foundation (Linux Foundation); 원 제안 OpenAI Codex·Amp·Google Jules·Cursor·Factoryagents.md표준·규약영어

코딩 에이전트용 "README"를 표방하는 오픈 포맷의 사양 사이트다. 필수 필드 없는 순수 마크다운으로 프로젝트 개요·빌드/테스트 명령·코드 스타일·테스트 지침·보안 고려를 권장 섹션으로 제시하고, README는 사람용 빠른 시작·기여 안내에 집중시키고 에이전트가 필요로 하는 상세 맥락은 별도 파일로 분리하라는 것이 존재 이유다. 모노레포에서는 에이전트가 디렉터리 트리에서 가장 가까운 파일을 읽어 하위 프로젝트별 지침이 우선하며, 명시적 사용자 채팅 지시는 파일 내용보다 항상 우선한다. 2025년 12월 9일 Linux Foundation 산하 Agentic AI Foundation(AAIF)이 출범하면서 OpenAI가 기여한 프로젝트로 MCP·goose와 함께 이관되어 특정 벤더에 묶이지 않은 규격이 되었다.

“Agents automatically read the nearest file in the directory tree, so the closest one takes precedence.”

여러 에이전트(Codex·Copilot·Cursor·Gemini CLI 등)를 섞어 쓰는 팀이 프로젝트 의도·제약·관례를 도구 중립 파일 하나에 두고 도구별 파일은 그것을 참조하게 만드는 SSOT 전략의 기준 규격이다. 사람용 README와 에이전트용 맥락을 분리하고, 가장 가까운 파일 우선 규칙으로 하위 모듈별 의도를 계층적으로 기록할 수 있다는 점이 의도 부채 대응의 출발점으로 인용된다.

저장소 지시 파일

Dale SeoEngineering Blog by Dale Seo블로그한국어

AI 에이전트가 프로젝트 전반의 지식이 부족해 엉뚱하게 작업하는 문제를 프로젝트 안내 파일로 해결하는 방법을 소개한다. AGENTS.md는 2025년 7월 OpenAI, Google(Jules), Cursor, Factory AI, Sourcegraph 등이 함께 만든 오픈 표준으로 20개 이상의 도구가 지원한다. 반면 CLAUDE.md는 Claude Code 전용 파일이다. 글은 아키텍처, 빌드·테스트 명령, 코드 스타일, 기술 스택 버전, 보안 주의점, 흔한 함정 등을 20~50줄 정도로 간결하게 적으라고 권한다.

“AI 에이전트에게 작업을 시키다 보면 프로젝트에 대한 전반적인 지식이 부족하여 엉뚱하게 작업을 진행할 때가 있습니다.”

한국어로 쓰인 AGENTS.md/CLAUDE.md 입문서다. 프로젝트의 맥락과 규칙을 에이전트에게 전달하는 첫 단계인 지시 파일의 표준 현황과 작성 원칙을 정리한다.

저장소 지시 파일

Boris Cherny (Anthropic, Claude Code 창시자)AI Engineer World's Fair 2025발표영어

천공카드와 초기 편집기에서 현대 언어까지 이어진 프로그래밍의 흐름을 짚은 뒤, Anthropic이 Claude Code를 의도적으로 '의견 없는(unopinionated)' 방식으로 설계한 이유를 설명하는 18분 12초 강연이다. 에이전트는 편집 전에 저장소를 탐색해 컨텍스트를 모으고 계획을 제안해야 하며, git 히스토리·저장소 지시 파일·재사용 가능한 마크다운 명령·기존 CLI 도구가 낯선 코드베이스를 추론할 구체적 맥락이 된다고 말한다. 로그를 파이프로 받아 구조화 출력을 내는 유닉스식 조합과, 별도 체크아웃·git worktree에서 여러 에이전트를 돌리고 공유 마크다운 파일로 조율하는 병렬 워크플로도 다룬다.

“Git history, repository instructions, reusable Markdown commands, and existing command-line tools give agents the concrete context needed to reason effectively about unfamiliar codebases.”

Claude Code를 만든 사람이 직접 git 히스토리와 저장소 지시 파일이 에이전트의 맥락이라고 말한다. 그래서 CLAUDE.md 같은 지시 파일과 커밋 히스토리를 가꿔야 할 실무 근거가 된다.

저장소 지시 파일커밋 히스토리·변경 출처강제 장치·기여 정책

박재영 (컬리)컬리 기술 블로그 (helloworld.kurly.com)블로그한국어

Claude Code로 하는 에이전트 개발을 예측 가능하게 만드는 컨텍스트 관리 전략을 정리한 글이다. 루트 CLAUDE.md에는 온보딩 내용을, 디렉터리별 CLAUDE.md에는 그 디렉터리에만 적용되는 컨벤션을 둔다. Plan Mode로 계획을 먼저 검증하고 작업을 한 번에 하나씩 쪼개 진행해 초반의 오해가 이후 코드 전체로 번지는 것을 막는다. Lost in the Middle, 학습 데이터 편향, 여러 항목을 동시에 추적하기 어려운 한계를 근거로 들고, 규칙을 나열하는 대신 실제로 검사하는 Agent Skills를 권한다.

“초반의 작은 오해가 이후 모든 코드에 영향을 미친다”

국내 커머스 회사가 CLAUDE.md 계층화, Plan Mode, 턴 단위 검증을 어떻게 설계했는지 보여 준다. 에이전트가 프로젝트 의도에서 벗어나는 것을 일찍 잡는 절차로 그대로 참고할 수 있다.

저장소 지시 파일강제 장치·기여 정책이해 유지 실천

Barry Zhang, Keith Lazuka, Mahesh Murag (Anthropic)Anthropic Engineering Blog블로그영어

Anthropic이 2025년 10월 16일 Agent Skills를 소개한 엔지니어링 글이다. 스킬은 SKILL.md 파일이 들어 있는 디렉터리이며, 에이전트에 기능을 더해 주는 지시·스크립트·리소스를 정리해 담는다. 글은 스킬 제작을 신입 사원용 온보딩 가이드를 꾸리는 일에 비유하고, 메타데이터 → SKILL.md 본문 → 연결 파일의 3단계 점진적 공개 덕분에 스킬에 담을 수 있는 맥락이 사실상 무제한이라고 설명한다. 2025년 12월 18일 갱신에서는 Agent Skills를 개방 표준으로 공개했다고 알렸다.

“Building a skill for an agent is like putting together an onboarding guide for a new hire.”

'온보딩 문서를 에이전트용으로 다시 쓰는 것'이라는 설계 의도를 원문에서 직접 확인할 수 있어, 팀의 절차 지식을 에이전트가 읽는 스킬로 옮기자는 주장의 근거로 쓸 수 있다.

저장소 지시 파일조직 지식 검색강제 장치·기여 정책

Dustin Ellis, Harald Kirschner, Joel Norman (Microsoft/GitHub)GitHub Universe 2025 (hands-on session material, GitHub repository)강의영어

GitHub Universe 2025 핸즈온 세션용 실습 저장소로, Copilot에 프로젝트 맥락을 넣는 커스터마이즈 방법을 단계별로 안내한다. 저장소 전체에 적용되는 .github/copilot-instructions.md와 API 전용 .github/instructions/API.instructions.md를 만들고, Copilot Chat의 'Generate Agent Instructions' 프롬프트로 지시 파일을 생성하는 절차를 다룬다. .github/agents의 커스텀 에이전트와 .github/skills의 에이전트 스킬도 저장소 안에 두고 활용하도록 구성되어 있다.

“Create a generic (project wide) GitHub Copilot Instructions file”

Copilot을 쓰는 팀이 저장소 안 어느 경로에 어떤 지시 파일·에이전트·스킬을 두는지 실습 순서대로 따라 할 수 있는 벤더 공식 자료다.

저장소 지시 파일

GitHubGitHub Docs공식 문서영어

Copilot 코드 리뷰는 PR을 리뷰할 때 저장소 커스텀 지침, 에이전트 지침, 에이전트 스킬을 base 브랜치가 아니라 변경이 있는 head 브랜치에서 읽는다. .github/instructions/ 아래 경로별 *.instructions.md 파일은 변경된 파일이 지침 범위와 일치할 때 자동으로 적용된다. Copilot Pro·Pro+·Max 플랜에서는 공개 프리뷰인 Copilot Memory를 켜서 Copilot이 저장소에 대해 학습한 세부를 저장하고 PR 리뷰에 쓰게 할 수 있으며, 문서는 이를 직접 작성하는 커스텀 지침과 따로 설명한다.

“When reviewing a pull request, Copilot reads repository custom instructions, agent instructions, and agent skills from the head branch (the branch with your changes), not the base branch.”

팀 결정을 리뷰 봇이 읽는 경로별 지침 파일로 옮길 때, 지침이 head 브랜치에서 읽힌다는 점을 알면 규칙을 바꾸는 PR이 그 PR 자체의 리뷰에 곧바로 반영된다는 것을 이해하고 운영할 수 있다.

저장소 지시 파일에이전트 메모리

AnthropicClaude Code Docs공식 문서영어

훅을 Claude Code 생명주기의 특정 지점에서 실행되는 사용자 정의 셸 명령으로 정의한다. 문서는 훅이 LLM의 선택에 기대지 않고 특정 동작을 항상 일어나게 하는 '결정론적 제어'를 준다고 설명하고, 프로젝트 규칙 강제를 주요 용도로 든다. 예제로 보호 파일 편집 차단(PreToolUse에서 exit 2), 컨텍스트 압축 뒤 핵심 맥락을 다시 넣는 SessionStart compact matcher를 제공한다. 판단이 필요한 조건은 Claude 모델이 평가하는 prompt 기반 훅이나 agent 기반 훅으로 다룰 수 있다고 안내한다.

“Hooks are user-defined shell commands. Claude Code runs them at specific points in its lifecycle, which gives you deterministic control: certain actions always happen rather than relying on the LLM to choose to run them.”

팀 규칙과 핵심 맥락을 지시 문장으로만 두지 않는 방법을 보여 준다. 훅으로 규칙 위반을 결정론적으로 막고, 압축 뒤에는 맥락을 자동으로 다시 넣는다. 이렇게 하면 에이전트가 의도에서 벗어나는 일을 줄일 수 있다.

저장소 지시 파일강제 장치·기여 정책

Cursor (Anysphere)Cursor Docs공식 문서영어

Cursor의 PR 리뷰 봇 Bugbot은 .cursor/BUGBOT.md 파일에서 프로젝트별 리뷰 규칙을 읽는다. 루트 파일은 항상 포함하고, 변경된 파일에서 위쪽 디렉터리로 올라가며 찾은 BUGBOT.md를 더한다. 학습 규칙은 저장소의 GitHub 팀 활동에서 자동으로 만들어지거나, 저장소 히스토리를 수동으로 백필해서 만들 수 있다. PR에 '@cursor remember [fact]' 댓글을 달면 그 사실이 학습 규칙으로 저장되어 이후 리뷰에 적용된다.

“You can also teach Bugbot new rules inline by commenting `@cursor remember [fact]` on any PR. Bugbot saves the fact as a learned rule and applies it to future reviews.”

디렉터리 단위 리뷰 규칙 파일과 PR 댓글로 결정을 가르치는 방식은 프로젝트의 의도를 리뷰 단계에서 AI에 전달하는 한 가지 방법이다. 모노레포에 그대로 적용해 볼 수 있다.

저장소 지시 파일에이전트 메모리

AnthropicClaude Code Docs공식 문서영어

Claude Code 스킬을 어디에 저장하느냐에 따라 어느 세션에서 적재되는지를 정리한 공식 문서다. 저장 위치는 enterprise(관리형 설정), personal(~/.claude/skills), project(.claude/skills), nested 하위 디렉터리, --add-dir로 추가한 디렉터리, plugin으로 나뉜다. 문서는 저장소에 커밋하면 같은 저장소에서 일하는 모두가, 플러그인이나 관리형 설정으로 배포하면 팀 전체가 스킬을 공유한다고 설명한다. 또 CLAUDE.md의 한 절이 '사실'이 아니라 '절차'로 커지면 사용할 때만 본문이 적재되는 스킬로 옮기라고 권한다. 같은 이름의 스킬이 겹칠 때는 enterprise가 personal보다, personal이 project보다 우선하므로 개인 스킬이 같은 이름의 저장소 공용 스킬 대신 실행된다.

“Enterprise over personal, and personal over project. With `deploy` in both `~/.claude/skills/` and the project's `.claude/skills/`, `/deploy` runs the personal one”

팀 공용 절차(저장소에 커밋한 스킬)와 개인 절차(~/.claude/skills)가 어디에 저장되고 어느 쪽이 우선하는지 알아야, 팀원마다 에이전트가 서로 다른 절차를 따르는 편차를 막을 수 있다. 사실은 CLAUDE.md에, 절차는 스킬에 두라는 구분도 에이전트가 읽을 의도 문서를 어떻게 나눌지에 대한 공급사의 공식 지침이다.

저장소 지시 파일강제 장치·기여 정책

Nicolás Miccio Palermo, Antonela Tommasel, J. Andrés Diaz-PacearXiv (cs.SE)논문영어

약 550개 오픈소스 저장소에서 추출한 ADR을 토픽 모델링·LLM 기반 분류·MADR 템플릿 준수 검사로 대규모 분석한 연구다. ADR은 존재(existence)·기술·프로세스 관련 결정을 자주 담지만, 대안(alternatives)·결정 동인(decision drivers)·일부 품질 관심사는 과소 기록된다고 보고한다. 또한 ADR 내용과 템플릿 절 사이의 반복적인 불일치를 관찰했다. 즉 ADR을 쓰더라도 "왜"와 "버린 대안"이 빠지는 경향이 실증적으로 확인되어, 기록의 존재보다 기록의 내용이 의도 부채를 좌우함을 시사한다.

“ADRs frequently capture existence, technology, and process-related decisions, while alternatives, decisions drivers, and some quality concerns remain under-documented.”

ADR을 도입해도 기각 대안과 결정 동인이 빠지기 쉽다는 실증 근거이므로, 팀 템플릿에서 그 두 절을 필수로 만들 이유가 된다.

결정 기록(ADR)측정과 실증

John Kennedy (Actual AI)Actual AI blog블로그영어

Nygard의 ADR을 사람 독자용 산문에서 에이전트 독자용 기록으로 재구성한 "agent-optimized ADR"을 제안한다. applies_to glob 스코프, MUST/MUST NOT 규범 규칙, R-IMG-001 같은 안정 ID, grep·lint 규칙·명령 같은 검증 수단 네 가지를 더해 에이전트가 관련 결정을 찾고, 범위를 정하고, 따르고, CI에서 준수를 확인할 수 있게 한다. CLAUDE.md, AGENTS.md, README, 위키에 같은 결정이 재진술되면 몇 달 안에 사본이 어긋나는 "컨텍스트 파일 부패"를 지적하며, 자사 Architecture Agent가 이런 기록을 자동 생성·중복 제거·유지한다고 소개하는 벤더 글이다.

“Context files rot. The same decision gets restated in CLAUDE.md, AGENTS.md, a README, and a wiki page, and the four copies disagree within a few months.”

결정 기록(ADR)을 에이전트가 검색·적용·검증할 수 있는 규칙으로 바꾸는 구체적 형식을 제시하고, 여러 컨텍스트 파일에 결정을 중복 기록할 때 생기는 부패 문제를 의도 부채의 한 원인으로 짚는다. 벤더 홍보 성격이 있으므로 인용 시 그 점을 명시한다.

결정 기록(ADR)저장소 지시 파일

박재홍 (@jaehong, 박재홍의 실리콘밸리)위키독스 블로그블로그한국어

Safe Intelligence의 Michal Cichra(전 Microsoft·Red Hat에서 10년간 단일 제품 유지보수) 발표를 정리한 한국어 글로, 원 발표의 행사명이나 영상 링크는 밝히지 않는다. 사람은 잊고 이직하며 LLM은 영속 기억이 없다는 "제한된 맥락" 문제를 출발점으로, ADR(왜·강제 방법·예시·scope), PRD(이유·문제·목표·여정), BDD(Cucumber)를 git hooks·CI·린터로 구성된 강제 루프에 넣어야 실효성이 있다고 주장한다. 레이어 분리로 N+1 쿼리를 막는 규칙은 모듈 import 린팅으로 강제하고, 위반 시 커밋을 거부하며 ADR 링크를 제공해 에이전트가 읽고 스스로 수정·재시도하게 한다. 비용으로 리서치 단계에서 컨텍스트 윈도우 절반 소모와 세션당 20~50회 압축을 인정하되, 규칙이 문서와 도구로 존재하면 압축 뒤에도 에이전트가 다시 찾아 따른다고 설명한다.

“결정의 이유가 어딘가에 명시적으로 적혀 있지 않으면, 에이전트는 그 결정을 알 방법이 없다.”

한국어로 읽을 수 있는 드문 1차 정리이며, 의도 부채의 원인을 "사람은 잊고 LLM은 기억이 없다"는 제한된 맥락으로 진단한 뒤 초점을 "기록"에서 "강제"로 옮긴 강제 루프 설계를 제시한다. ADR에 scope와 강제 도구를 함께 적고 린트·CI 실패 메시지에 ADR 링크를 붙이는 방식은 프런트엔드 저장소에도 그대로 적용할 수 있다.

결정 기록(ADR)명세 주도 개발강제 장치·기여 정책

yureki_labDEV Community블로그영어

Claude Code 기반 자율 구현 시스템이 의도적으로 비관례적인 설계(웹훅 대신 폴링, 동기 파일 쓰기, 고정 의존성)를 세션마다 "교정"해 되돌리는 문제를 다룬다. 지시 파일에 규칙만 추가하는 방식은 우회되었고, 해결책은 2011년식 ADR을 에이전트 메모리로 쓰는 것이었다. Scope 필드에 파일 glob을 넣고, docs/adr/INDEX.md로 관련 ADR만 로드하며, 에이전트도 Status: proposed ADR 초안을 쓰게 하는 세 가지 조정 뒤 6개월간 정착된 결정을 재론하지 않았다고 저자가 보고한다.

“Six months later, the agent hasn't relitigated a single settled decision.”

규칙 나열보다 결정의 "이유"를 기록한 ADR이 에이전트의 되돌림을 막았다는 실제 운영 사례이며, Scope glob과 INDEX.md라는 작은 구조를 CLAUDE.md와 결합하는 방식은 프런트엔드 저장소에 바로 옮길 수 있다.

결정 기록(ADR)저장소 지시 파일에이전트 메모리

Ivan StetsenkoarXiv (cs.SE)논문영어

AI 코딩 에이전트가 코드의 생산자이자 소비자가 되면서 커밋이 diff만 남기고 제약·기각 대안·향후 맥락을 버리는 문제를 "Decision Shadow"로 정의한다. git 네이티브 trailer(Constraint, Rejected, Confidence, Scope-risk, Reversibility, Directive, Tested, Not-tested, Related)로 커밋 메시지를 자체 완결적 결정 기록으로 재구성하는 Lore 프로토콜을 제안하며, git 외 인프라 없이 CLI로 질의하고 셸을 쓰는 에이전트라면 누구나 발견할 수 있게 한다. 본문은 ADR이 아키텍처 수준 결정만 다루고 구현 수준 결정은 놓친다고 보고 Lore를 그 보완 층으로 자리매김하며, ADR·Code Digital Twin·Git Context Controller·git-ai·AI 생성 커밋 메시지 다섯 접근과 비교하고 반론을 스트레스 테스트한다. 정량 결과는 없고, 두 팀·6개월 규모의 경험적 검증 경로를 향후 과제로 제시한다.

“Each commit captures a code diff but discards the reasoning behind it - the constraints, rejected alternatives, and forward-looking context that shaped the decision. I term this discarded reasoning the Decision Shadow.”

ADR을 따로 쓸 여유가 없는 팀이 커밋 메시지 규약만으로 기각 대안과 제약을 남기고 에이전트가 수정 전에 `lore constraints`·`lore rejected`로 조회하게 하는 방식이라, git 고고학과 결정 기록, 에이전트 지시 파일을 잇는 실용적 관점을 준다. 다만 아직 경험적 검증이 없는 제안 단계임을 함께 밝혀야 한다.

결정 기록(ADR)커밋 히스토리·변경 출처에이전트 메모리저장소 지시 파일

Microsoft (Chad Kittel)Microsoft Learn / Azure Well-Architected Framework공식 문서영어

솔루션 아키텍트의 가장 중요한 산출물 중 하나로 ADR을 정의하며, 아키텍처는 결정의 누적이므로 ADR은 시스템이 지금의 모양이 된 경위와 이유의 기록이라고 설명한다. ADR은 append-only 로그로 운영해 수락된 기록은 편집하지 않고 새 기록으로 대체·링크하며, 브라운필드 워크로드도 알려진 과거 결정을 소급 작성하라고 권한다. 각 기록에는 문제 진술·고려한 옵션·결정 결과(트레이드오프·신뢰 수준)·상태를 담고, 근거 없는 기록은 시간이 지나면 가치를 잃는다고 본다. 기록되지 않은 결정은 잊혀 반복 논쟁이나 원래 의도를 모른 채 위배하는 변경으로 이어진다고 명시하며, 워크로드 문서 저장소를 단일 진실 원천으로 삼으라고 권고한다.

“A decision that's made but never recorded will likely be forgotten, leading to repeated debates or later changes that unknowingly contradict the original intent.”

"기록되지 않은 결정은 원래 의도를 모른 채 위배된다"는 문장이 의도 부채를 그대로 정의하고, append-only 운영·신뢰 수준 기록·브라운필드 소급 작성·단일 진실 원천 저장소 같은 실무 지침을 주는 주요 클라우드 벤더의 공식 문서다.

결정 기록(ADR)강제 장치·기여 정책

Mneme HQGitHub (MIT)도구영어

Mneme는 ADR을 수동적인 문서로 두지 않고 구조화된 거버넌스 레코드(.mneme/project_memory.json)로 컴파일해, AI 코딩 에이전트의 변경을 결정론적으로 판정하는 오픈소스 도구다. 판정은 PASS·WARN·FAIL 세 가지이고, LLM 판정에 기대지 않아 같은 입력과 결정 상태면 같은 결과가 나온다. 에이전트가 차단형 pre-tool 훅을 제공하면 파일을 바꾸기 전에 개입하고, 그런 훅이 없는 경로는 변경 후 감사로 잡는다. GitHub Actions·GitLab CI에서는 CLI 기반 CI 게이트로 동작한다.

“It keeps recorded engineering decisions active as AI coding systems propose and modify code, instead of leaving ADRs as passive documentation.”

ADR을 쓰는 데서 멈추지 않고, 에이전트 훅과 CI에서 기록된 결정을 차단 판정으로 잇는다. 결정 기록을 강제하는 가장 직접적인 오픈소스 구현 예다.

결정 기록(ADR)저장소 지시 파일강제 장치·기여 정책

Vincent Saluzzo (Teads)vincentsaluzzo.com (personal blog; republished on Teads Engineering, Medium)블로그영어

Teads의 성과 광고 어트리뷰션 파이프라인에서 "visit" 이벤트가 왜 일반 전환처럼 post-click/post-view로 집계되지 않는지 아무도 모르는 사례를 든다. ADR이 없고 원래 구축자들이 퇴사해 저자는 두 가지 추정만 할 수 있었다. LLM은 코드베이스 구조는 잘 추출하지만 "왜"는 추론하지 못하며, AI는 같은 아키텍처 결정에 두 번 다른 경로를 택할 수 있으므로 기록할 가치는 AI 출력이 아니라 사람의 추론에 있다고 주장한다. Nygard의 5개 필드에 date와 rejected alternatives를 더하고 5분 내 읽을 수 있어야 하며, ADR은 설계 문서·제품 스펙·기술 스펙과 구분해야 한다고 정리한다.

“Think of ADRs as the long-term memory that LLMs don't have. You write them once, and they compound in value over time.”

실제 팀에서 ADR 부재가 어떻게 "왜"의 상실로 이어졌는지와 에이전트 코딩 도구 시대에 ADR을 왜 다시 도입했는지를 함께 보여 주는 현장 기록으로, 의도 부채의 구체 사례와 결정 기록 처방을 동시에 제공한다.

결정 기록(ADR)강제 장치·기여 정책

Xiyu Zhou, Ruiyin Li, Peng Liang, Beiqi Zhang, Mojtaba Shahin, Zengyang Li, Chen YangarXiv:2504.20781 (v3, 2025-12-09); accepted for publication in ACM Transactions on Software Engineering and Methodology (TOSEM)논문영어

소프트웨어 아키텍처 결정의 설계 근거(Design Rationale)를 LLM이 얼마나 잘 생성하는지 실증적으로 평가한 연구다. Stack Overflow 게시물 50건, GitHub 이슈 25건, GitHub 토론 25건에서 100개의 아키텍처 문제를 모아 5개 LLM에 zero-shot, chain-of-thought, LLM 에이전트 세 가지 프롬프트 전략을 적용하고 전문가가 작성한 근거를 정답으로 삼아 비교했으며, 실무자 6명과 반구조화 인터뷰로 신뢰성과 실용성을 검토했다. 재현율은 높지만 정밀도가 낮아, LLM이 만든 근거는 그대로 결정 기록으로 쓰기보다 사람이 검토하는 보조 자료로 삼아야 함을 시사한다.

“the Precision of LLM-generated DR with the three prompting strategies ranges from 0.267 to 0.278, Recall from 0.627 to 0.715, and F1-score from 0.351 to 0.389.”

AI에게 ADR 초안이나 '왜 이렇게 설계했는가' 설명을 생성시킬 때 얼마나 믿을 수 있는지에 대한 정량적 기준을 제공한다. 정밀도가 낮다는 결과는 의도 부채를 AI로 자동 복원하려는 시도에 사람의 검토가 필수임을 뒷받침한다.

결정 기록(ADR)측정과 실증

adr GitHub organization (MADR project)adr.github.io공식 문서영어

MADR은 마크다운으로 결정을 기록하는 ADR 템플릿으로, 맥락과 문제 진술·결정 동인·고려한 옵션·결정 결과·결과(Consequences)·확인(Confirmation)·각 옵션의 장단점·추가 정보 절로 구성된다. 아키텍처 결정을 "아키텍처적으로 중요한 요구사항을 다루는, 정당화된 소프트웨어 설계 선택"으로 정의하면서도, 중요한 결정이면 무엇이든(IDE·라이브러리 선택 등) 구조적으로 기록하라고 권한다. 2024년 9월 17일 공개된 4.0.0은 full 외에 bare·minimal 템플릿을 함께 제공한다. 고려한 옵션과 장단점을 명시적으로 남기게 설계되어 있어 채택하지 않은 대안이 기록에 남는다.

“Since we believe that any (important) decision should be captured in a structured way, we offer the MADR template to capture any decision.”

기각 대안과 그 이유, 결정 준수 확인 방법까지 남기게 하는 사실상의 표준 ADR 템플릿이라, 사람과 코딩 에이전트가 함께 읽을 결정 기록의 골격으로 바로 쓸 수 있다.

결정 기록(ADR)

Olaf Zimmermann (OST / socadk)Design Practice Repository (GitHub Pages)공식 문서영어

Y-statement는 아키텍처 결정 하나를 "In the context of …, facing …, we decided for … (and against …), to achieve …, accepting that …"라는 한 문장으로 적는 템플릿이다. 페이지는 이 WH(Y) 템플릿이 Zimmermann의 SATURN 2012 발표에서 처음 제안되었고 2013년부터 HSR/OST 강의에서 쓰였으며, Fairbanks가 WICSA 2011에서 발표한 Architecture Haiku의 결정 서술 형식에서 영감을 받았다고 밝힌다. "and against" 절이 기각한 대안을, "accepting that" 절이 감수한 결과를 명시하도록 강제하므로 가장 가벼운 형식으로 결정 의도를 보존한다. 형식이 일관되지 않아도 내용이 정확하고 최신이면 결정 로그가 없는 것보다 낫다고 권고한다.

“An inconsistently formatted decision log is better that none (assuming that its content is accurate and current).”

한 문장이면 되므로 PR 설명이나 CLAUDE.md·AGENTS.md 한 줄에 기각한 대안과 감수한 단점까지 남기는 최소 형식으로 즉시 채택할 수 있다. AI 에이전트가 코드를 고치기 전에 읽을 "왜"를 가장 낮은 비용으로 축적하는 방법이다.

결정 기록(ADR)

Juan Pablo BuriticáOpensource.com (원문은 Juan's And Zeroes 블로그, 허가 하에 재게재)기사영어

카풀 플랫폼 Ride에서 첫 6개월 만에 3명에서 25명 이상으로 커진 6개국 분산 팀에 기술 RFC를 도입한 경험을 정리한 글이다. 계기는 한 프런트엔드 엔지니어가 "프런트엔드 스택이 Ember인데 왜 데이터 대시보드는 React로 만들어졌는가"를 물은 사건으로, 팀 전체를 대신한 중요한 결정이 팀에 공유되지 않았음을 드러냈다. RFC 작성 시점 판단의 어려움, 포용에 따르는 책임(최소 2일~최대 1주 공개), 신뢰 문제의 가시화, 권력 역학 관리, [newbie] 태그를 통한 심리적 안전, 리더십의 적정 추상화 수준 참여라는 여섯 교훈을 제시한다. 현재와 미래의 팀원에게 결정의 "why and how"에 대한 맥락을 주는 것이 더 행복하고 효과적인 분산 조직 운영의 바탕이 되었다고 결론짓는다.

“Giving team members, present and future, the context into why and how decisions have been made has allowed me to run happier and more effective distributed engineering organizations.”

프런트엔드 스택 선택(React vs Ember)의 이유가 공유되지 않아 생긴 문제를 RFC로 푼 사례로, 결정의 "왜"가 팀에 남지 않는 의도 부채를 프로세스로 해결한 프런트엔드 팀의 직접적인 선례다. "현재와 미래의 팀원"을 위한 맥락이라는 표현은 다음 편집자(사람이든 AI 에이전트든)를 위한 결정 기록의 필요성과 맞닿는다.

결정 기록(ADR)강제 장치·기여 정책

Michael Nygard (Cognitect)Cognitect blog블로그영어

ADR(Architecture Decision Record)을 처음 제안한 글이다. 결정 하나와 그 결정을 낳은 맥락을 짧은 텍스트 파일 하나에 기록하자고 제안하며, 제목·맥락·결정·상태·결과의 5개 절, 저장소 내 doc/arch/adr-NNN.md 배치, 단조 증가하며 재사용하지 않는 번호를 규정한다. 새로 합류한 사람이 결정의 근거와 결과를 모르면 맹목적으로 수용하거나 맹목적으로 바꾸는 두 선택지밖에 없다고 지적하는데, 이것이 의도 부채 문제의 원형적 서술이다.

“Without understanding the rationale or consequences, this person has only two choices: Blindly accept the decision. ... Blindly change it.”

모든 ADR 도구와 에이전트용 결정 기록의 출발점이며, "근거를 모르면 맹목적으로 수용하거나 맹목적으로 바꾼다"는 문제 정의가 의도 부채 그 자체이므로 가장 먼저 읽어야 한다.

결정 기록(ADR)강제 장치·기여 정책개념 틀과 이론

Amazon Web ServicesAWS Prescriptive Guidance공식 문서영어

AWS가 정리한 ADR(아키텍처 결정 기록) 운영 프로세스 문서다. 수락된 ADR은 불변이며 새 통찰이 생기면 새 ADR을 제안해 이전 것을 Superseded 상태로 바꾸고, 대상 범위는 구조·비기능 요구·의존성·인터페이스·구축 기법으로 정한다(Richards & Ford 2020 인용). 리뷰 회의는 평균 10~15분의 문서 읽기 슬롯으로 시작하고, 거부된 ADR에도 거부 이유를 남겨 같은 주제의 논의 재발을 막으며, 코드 리뷰에서 ADR 위반을 발견하면 해당 ADR 링크와 함께 수정을 요청한다. ADR이 구현 방법이 아니라 결정 이유에 초점을 맞추므로 결정에 참여하지 않은 아키텍트가 나중에 뒤집는 것을 막는다고 명시한다.

“Understanding why the team made the decision makes it easier for other team members to adopt the decision, and prevents other architects who weren't involved in the decision-making process to overrule that decision in the future.”

거부된 결정까지 이유를 남기고, 코드 리뷰에서 ADR을 근거로 수정을 요청하는 절차가 명시돼 있어 팀 프로세스로 의도 부채를 줄이는 구체적 운영 모델이 된다. 결정 로그가 "왜"를 보존해 나중에 합류한 사람이 결정을 임의로 뒤집지 못하게 한다는 점이 의도 부채 정의와 직접 맞닿는다.

결정 기록(ADR)강제 장치·기여 정책

송영목 (SK AX)SK DevOcean블로그한국어

명세를 개발 전체를 지배하는 유일한 진실 공급원(SSOT)으로 두고 코드를 그 표현물로 보는 명세 기반 개발(SDD)을 GitHub Spec Kit으로 실습한다. Constitution으로 프로젝트 원칙을 정한 뒤 Specify(무엇·왜) → Plan(어떻게) → Tasks → Implement 순으로 진행한다. 개발자는 AI라는 파일럿을 올바른 방향으로 이끄는 '관제탑' 또는 '조향사' 역할을 맡는다.

“명세가 원본이고, 코드는 표현물이다”

국내 IT 서비스 기업 개발자가 스펙 주도 개발을 실습하는 한국어 가이드다. 코드 작성 전에 '왜'를 명세에 먼저 적고 코드를 그 명세에서 파생시키는 흐름을 보여 준다.

명세 주도 개발

Shuvendu K. LahiriarXiv (submitted 2026-03-17)논문영어

AI 에이전트가 만든 코드는 '그럴듯하게 생성될 뿐 올바르게 생성되지는 않는다'고 보고, 사용자가 뜻한 바와 프로그램이 실제로 하는 일 사이의 거리를 'intent gap'으로 정의한다. 해법으로 비형식적 요구를 검사 가능한 명세로 옮기는 '의도 형식화'를 제안하며, 가벼운 테스트, 코드 계약, Dafny·Verus 같은 논리 계약, DSL로 이어지는 신뢰성 스펙트럼을 제시한다. 명세가 맞는지 판정할 오라클은 사용자뿐이므로 명세 검증이 핵심 병목이라고 보고, soundness와 completeness 기반 지표를 과제로 든다.

“The gap between informal natural language requirements and precise program behavior -- the intent gap -- has always plagued software engineering, but AI-generated code amplifies it to an unprecedented scale.”

'이 코드가 원래 뭘 하려던 건지'를 주석이 아니라 테스트와 계약 같은 검사 가능한 명세로 남겨야 에이전트가 어기지 못한다는 논리의 1차 학술 근거다.

명세 주도 개발개념 틀과 이론

Thoughtworks Technology Advisory BoardThoughtworks Technology Radar Vol 34 (2026년 4월), Tools · Assess보고서영어

Thoughtworks Technology Radar Vol 34(2026년 4월)가 Tools 분야 Assess 링에 올린 오픈소스 스펙 주도 개발(SDD) 프레임워크 OpenSpec 블립이다. 코드 생성 전에 개발자와 AI 에이전트가 무엇을 만들지 합의하는 가벼운 명세 층을 두되, 전체 명세를 처음부터 쓰지 않고 propose → apply → archive 세 단계로 변경 제안(spec delta)을 쌓는 방식이라 기존 시스템에 적합하다고 평가한다. GitHub Spec Kit이나 Superpowers 같은 프레임워크는 브라운필드보다 그린필드에 더 맞고, BMAD류의 경직된 워크플로와 달리 반복적이고 도구 비종속적이라고 대비한다. 다만 모델의 기본 능력이 발전하면 전용 SDD 도구의 필요가 줄 수 있으니 native 기능을 계속 관찰하며 재평가하라고 덧붙인다.

“We particularly like OpenSpec's focus on spec deltas rather than defining a complete specification upfront”

이미 역사가 긴 코드베이스에 통째 명세를 새로 쓰기 어려운 팀에게, 변경 단위로 의도를 제안서(spec delta)로 남기고 보관(archive)하는 방식은 의도 부채를 점진적으로 갚는 현실적 경로다. 에이전트가 코드를 고치기 전에 사람과 합의한 명세가 남으므로 '왜 이렇게 바꿨는가'가 코드와 함께 축적된다.

명세 주도 개발결정 기록(ADR)강제 장치·기여 정책

Sam KDZone기사영어

2026년 7월 21일 DZone에 실린 비평으로, Spec Kit·OpenSpec·BMAD·Kiro 같은 SDD 도구가 "명세가 정본으로 남을 수 있다"는 가정 위에 서 있지만 설계 문서·위키·README가 20년 넘게 코드와 동기화되지 못한 것과 같은 이유로 그 가정이 성립하지 않는다고 주장한다. 코드 수정은 빠르고 결과가 보이지만 문서 수정은 느리고 보이는 게 없어, 에이전트가 문서화되지 않은 제약을 만나 인라인으로 고치고 나면 이후 작업이 낡은 가정을 조용히 물려받는다고 설명한다. 해법으로 더 엄격한 명세 대신, lockfile이나 생성 문서처럼 코드와 실행 중인 시스템에서 명세를 추론·갱신해 사람이 기억하지 않아도 자동 유지되는 산출물로 만들자고 제안한다.

“infer and update the spec from what the code and the running system actually do, the same way you'd treat generated docs or a lockfile — maintained automatically, not maintained by someone remembering to do it.”

명세를 새로 쓰는 것보다 '낡지 않게 유지하는 메커니즘'이 없으면 의도 부채가 문서 부채로 이름만 바뀐다는 점을 짚어, 도구 선택 전에 유지 전략(사람의 기억이 아닌 자동 갱신)을 먼저 정하게 만든다.

명세 주도 개발개념 틀과 이론

Wei Zhang, Jessie Jie Xia (Thoughtworks)martinfowler.com기사영어

Thoughtworks의 Wei Zhang과 Jessie Jie Xia가 2026년 4월 28일 martinfowler.com에 발표한 방법론으로, 프롬프트를 일급 배포 산출물(first-class delivery artifact)로 다룬다. REASONS 캔버스(Requirements·Entities·Approach·Structure·Operations·Norms·Safeguards)의 요구(R)와 접근(A), 그리고 앞 단계의 분석 맥락에 무엇을 왜 해결하는지와 수용한 트레이드오프를 명시적으로 기록한다. /spdd-prompt-update(요구→프롬프트)와 /spdd-sync(코드→프롬프트) 명령으로 프롬프트와 코드 사이의 드리프트를 막는 양방향 동기화를 유지한다. 저자들은 절대적 결정성을 보장하지는 않으며 추상화·모델링 역량 요구가 높아 시니어 아키텍트용 방법처럼 보일 수 있다고 인정한다.

“The Canvas encodes the rationale. R (Requirements with DoD), A (Approach), and the Step 3 analysis context explicitly record what we are solving, why, and which trade-offs we accepted.”

명세(캔버스)에 '왜'와 수용한 트레이드오프까지 담고 코드 변경을 다시 프롬프트로 되돌리는 동기화 워크플로라, 의도가 코드와 함께 버전 관리되도록 하여 의도 부채를 구조적으로 막는 설계의 참고 모델이 된다.

명세 주도 개발결정 기록(ADR)강제 장치·기여 정책

Hartwig Grabowski (Hochschule Offenburg)arXiv preprint, cs.SE (submitted 2026-06-25)논문영어

AI 보조 개발에서 생기는 두 가지 실패로, 에이전트가 저장소 전체를 추론하다 성능이 떨어지는 '컨텍스트 폭발'과 코드만 바뀌고 명세는 그대로 남는 '조용한 스펙-코드 드리프트'를 든다. 대안으로 계약과 설계를 분리한 노드로 이루어진 기계 판독형 스펙 그래프를 두고, 그 위에 Spine 컨텍스트 조립기, 수직 슬라이스 성장 프로토콜, drift gate를 결합한다. drift gate는 SPEC.md에서 뽑은 Intent Graph와 정적 분석(import·export·라우트·테스트)으로 만든 Evidence Graph를 비교하고, 둘이 어긋나면 머지를 막는다. 정량 평가 없이 작은 예제(할인이 있는 결제)만으로 설명하는 설계 제안 단계다.

“spec and code are always aligned, or the commit does not land.”

스펙과 코드의 드리프트를 리뷰어 판단에 맡기지 않고 머지 게이트로 막는 방식이다. 오류와 경고의 분류 기준이 구체적이어서 의도 문서를 코드와 함께 유지하는 CI 규칙을 설계할 때 참고할 수 있다.

명세 주도 개발조직 지식 검색강제 장치·기여 정책

Dave Farley (speaker) / recap by Kai HendryAI Native DevCon London 2026 (2026-06-01~02)발표영어

AI Native DevCon London 2026에서 Dave Farley가 한 '바이브 코딩' 강연을 Kai Hendry가 참관기로 정리한 글이다. Farley는 피드백 루프·테스트 가능성·엔지니어링 규율 없는 바이브 코딩이 '빠르게 움직이는 기술 부채'를 만든다고 본다. 처방으로는 인수 기준을 Given/When/Then 형식으로 쓰고 에이전트가 그것을 바탕으로 작업하게 하라고 제시한다. 산문 설명이 아니라 정밀하고 테스트 가능한 인수 기준이 에이전트 산출물의 품질을 좌우하는 명세라는 것이 요지다.

“Precise, testable ACs are the spec quality that actually drives good agent output — not prose descriptions, not vibes.”

의도를 프롬프트 산문 대신 Given/When/Then 인수 기준으로 남기면 에이전트와 후임 개발자가 모두 같은 형태로 기능의 의도를 읽고 검증할 수 있다.

명세 주도 개발강제 장치·기여 정책

Nikhil Swaminathan, Deepak Singh (AWS)kiro.dev 블로그 (AWS)블로그영어

AWS가 2025년 7월 14일 발표한 스펙 주도 에이전트 IDE Kiro의 소개 글이다. 프롬프트만으로 동작하는 앱을 만들 수 있지만 모델이 어떤 가정을 했고 어떤 결정을 내렸는지가 문서로 남지 않아 프로덕션으로 가기 어렵다고 문제를 정의한다. 한 줄 프롬프트를 EARS 표기 수락 기준을 가진 요구사항 문서, 데이터 흐름도·TypeScript 인터페이스·DB 스키마·API 엔드포인트를 담은 설계 문서, 요구사항에 연결된 태스크 목록으로 전개한다. 코드를 고친 뒤 스펙을 갱신하거나 스펙을 고쳐 태스크를 새로 뽑는 양방향 동기화와, 파일 저장 같은 이벤트에 반응하는 훅으로 문서와 구현의 불일치를 막으려 한다.

“What assumptions did the model make when building it? You guided the agent throughout, but those decisions aren't documented.”

요구사항·설계·태스크가 저장소에 문서로 남고 코드 변경 후 스펙을 되돌려 갱신하는 흐름은, AI가 만든 결정과 가정을 다음 편집자(사람·에이전트)가 발견할 수 있게 하려는 의도 부채 대응의 구체적 제품 사례다.

명세 주도 개발강제 장치·기여 정책

Colin Eberhardt (Scott Logic)Scott Logic 블로그블로그영어

Scott Logic의 Colin Eberhardt가 2025년 11월 26일 자신의 SvelteKit·Firestore 기반 카트 레이싱 PWA(KartLog)에 GitHub Spec Kit을 적용해 서킷 관리 기능과 위치 기반 기능 두 증분을 만들고, 같은 범위를 반복 프롬프팅으로 다시 만들어 비교한 실험 보고다. 첫 증분은 에이전트 실행 33분 30초에 마크다운 2,577줄·코드 689줄을 만들고 리뷰에 3.5시간이 들었고, 둘째 증분은 23분 30초에 마크다운 2,262줄·코드 약 300줄·리뷰 약 2시간이 들었으며, 반복 프롬프팅은 실행 8분·코드 리뷰 15분·기능 테스트와 수정 9분으로 마크다운 없이 코드 1,000줄을 만들었다. Spec Kit 구현에서는 변수 circuitsData가 데이터스토어에서 채워지지 않는 단순한 버그가 나왔고 반복 프롬프팅 구현에는 버그가 없었다고 밝힌다. 저자는 코드는 추론·검증 가능한 형식 언어라서 법이 되지만 Spec Kit식 마크다운 명세는 그런 형식성이 없어 신뢰할 법이 못 되며, 순수한 형태의 SDD는 워터폴로의 회귀이자 실행 가능한 프로세스가 아니고 현재 가장 빠른 길은 반복 프롬프팅과 리뷰라고 결론짓는다.

“Code is law because it is formal language you can reason about. You can test it. You can prove it is right or wrong. Specifications, or at least ones expressed in the markdown format of Spec Kit, lack this formality.”

명세를 정본으로 삼는 SDD 접근이 실제로 얼마나 많은 마크다운과 사람 리뷰 시간을 요구하는지 수치로 보여주는 드문 1차 실험 기록이라, 의도 부채를 명세 문서로 해소하려는 접근의 비용과 한계(마크다운 명세의 비형식성, 워터폴 회귀)를 설명할 때 반례로 인용할 수 있다.

명세 주도 개발측정과 실증이해 유지 실천

Thoughtworks Technology Advisory BoardThoughtworks Technology Radar Vol 33 (2025년 11월)보고서영어

Thoughtworks Technology Radar Vol 33(2025년 11월)이 spec-driven development를 Assess 링에 올린 블립이다. 구조화된 기능 명세에서 시작해 여러 단계로 쪼개는 워크플로로 정의하고, Kiro(요구사항·설계·태스크 3단계), spec-kit(불변 원칙 'constitution' 추가), Tessl Framework(코드가 아니라 명세 자체가 유지 산출물)를 대비한다. 워크플로가 정교하고 의견이 강하며 작업 크기에 따라 거동이 크게 달라지고 리뷰하기 어려운 긴 명세를 만든다고 평가하면서, 'AI를 위해 세밀한 규칙을 손으로 쓰는 것은 결국 확장되지 않는다'는 bitter lesson을 다시 배우는 중일 수 있다고 경고한다. 같은 권의 테마 섹션은 SDD가 '증분 배포를 위한 단일 정본' 역할을 할 수 있는지 계속 논쟁 중이며, 과도한 사전 명세와 빅뱅 릴리스로 회귀할 위험이 있다고 밝힌다.

“We may be relearning a bitter lesson — that handcrafting detailed rules for AI ultimately doesn't scale.”

업계 대표 기술 레이더가 SDD를 아직 '평가(Assess)' 단계로 두고 명세 과잉과 워터폴 회귀, 손으로 쓴 규칙의 확장 한계를 경고하므로, 의도 부채 해법으로 명세를 단일 정본으로 삼으려 할 때의 위험 범위를 가늠하는 기준선이 된다. 같은 권에서 팀 공유 지침 파일은 Adopt, AGENTS.md는 Trial로 두어 '가벼운 공유 지침'과 '무거운 명세'의 성숙도 차이를 한 자료 안에서 대비할 수 있다.

명세 주도 개발저장소 지시 파일강제 장치·기여 정책

Den Delimarsky (GitHub)The GitHub Blog블로그영어

GitHub이 2025년 9월 2일 공개한 Spec Kit 소개 글로, 목표만 설명하고 코드를 받는 '바이브 코딩'이 프로토타입에는 좋지만 겉보기에 맞아 보여도 제대로 동작하지 않는 코드를 만들기 쉽다고 진단한다. Specify(사용자 여정·성공 기준) → Plan(기술 스택·아키텍처·제약) → Tasks(작고 검토 가능한 단위) → Implement의 4단계로 코딩 에이전트를 안내하며, 조직의 보안 정책·규정·디자인 시스템 제약을 프롬프트가 아니라 명세와 기술 계획 안에 넣어 처음부터 반영되게 하라고 권한다. 명세는 한 번 쓰고 치우는 문서가 아니라 구현·체크리스트·작업 분해를 이끄는 살아 있는 산출물이며, "코드가 정본"에서 "의도가 정본"으로 옮겨간다고 선언한다.

“We're moving from 'code is the source of truth' to 'intent is the source of truth.'”

의도 부채를 '명세를 코드 밖의 정본으로 유지'하는 방식으로 줄이려는 흐름의 대표 사례이며, Claude Code·Copilot 등 이미 쓰는 도구 위에 바로 얹을 수 있는 가장 보급된 SDD 툴킷이라 진입 비용이 낮다. /speckit.constitution(불변 원칙)과 /speckit.converge(코드와 명세 대조)는 결정 근거와 제약을 에이전트가 읽을 수 있는 산출물로 남기는 구체적 장치다.

명세 주도 개발저장소 지시 파일강제 장치·기여 정책

Simon Maple (Tessl)Tessl 블로그블로그영어

Tessl이 2025년 9월 23일 Tessl Framework와 Spec Registry 출시를 알린 글이다. 에이전트형 코딩 도구가 코드에 너무 빨리 뛰어들어 잘못된 해법·미완성 작업·API 환각·버전 혼동·의도치 않은 부작용을 낳는다고 진단하고, 코딩 전에 명세(spec) 또는 AI가 생성한 "vibe-spec"으로 무엇을 만들지 정의하게 한다. 명세는 코드베이스 안에 장기 기억으로 남아 앱이 진화하는 동안 에이전트를 안내하고 테스트와 짝지어 가드레일 역할을 한다. 레지스트리는 1만 개 이상의 사전 제작 명세로 오픈소스 라이브러리 사용법을 안내하며, 팀·조직 고유의 기술 스택·내부 라이브러리·보안 정책 같은 규칙도 명세로 담을 수 있다.

“These instructions live in the codebase as long-term memory, guiding agents as the app evolves and pairing with tests to enforce guardrails so existing functionality isn't broken.”

명세를 코드베이스 안의 장기 기억으로 두어 에이전트가 의도를 잃지 않게 한다는 발상은 의도 부채를 명세 산출물로 줄이려는 벤더 접근의 실제 제품 사례다. 외부 라이브러리 사용법뿐 아니라 팀 내부 규칙·제약을 같은 형식으로 남기게 한다는 점이 이 페이지의 SSOT 논의와 직접 맞닿는다.

명세 주도 개발조직 지식 검색

Sean Grove (OpenAI)AI Engineer World's Fair 2025, San Francisco (AI Engineer YouTube 채널, 2025-07-11 게시; 공식 transcript 페이지 https://ai.engineer/talks/8rABwKRsec4-specifications-are-the-new-code)발표영어

OpenAI의 Sean Grove가 2025년 AI Engineer World's Fair(샌프란시스코)에서 발표한 강연으로, 코드는 프로그래머가 만드는 가치의 10~20%이고 나머지 80~90%는 구조화된 의사소통이라고 주장한다. 바이브 코딩에서 프롬프트는 사라지고 생성된 코드만 남는 관행을 '소스는 버리고 컴파일된 바이너리만 보관하는 것'에 비유하며, 코드는 의도의 손실 있는 투영이므로 의도와 가치를 담은 명세(spec)를 버전 관리되는 정본 산출물로 삼아 문서·평가·모델 행동(그리고 코드)을 거기서 파생하자고 제안한다. 예시로 OpenAI Model Spec을 들어, 사람이 읽을 수 있는 버전 관리 마크다운 파일 모음이며 각 조항 식별자가 어려운 프롬프트 파일과 연결되어 구체적 성공 기준을 제공한다고 설명한다.

“Code is sort of 10 to 20 percent of the value that you bring. The other 80 to 90 percent is in structured communication.”

프롬프트(의도)를 버리고 코드만 남기는 습관이 왜 의도 부채를 만드는지 '소스를 버리고 바이너리만 보관한다'는 비유로 가장 압축적으로 설명하는 강연이라, 팀에 '왜 명세를 정본으로 남겨야 하는가'를 설득할 때 인용하기 좋다. 다만 Model Spec 사례는 모델 행동 정렬용 명세이며 일반 코드베이스의 설계 근거 관리 사례는 아니라는 점을 함께 적어야 한다.

명세 주도 개발개념 틀과 이론

Sean Grove (OpenAI, 현 Linzumi 창업자)AI Engineer World's Fair 2025, San Francisco발표영어

팀들이 생성된 코드는 남기고 프롬프트는 버리는 관행을, 소스는 버리고 컴파일된 바이너리만 정성껏 보관하는 것에 비유하며 의도의 지속적 기록이 사라진다고 지적한 21분 36초 강연이다. 코드는 의도의 손실 있는 투영이므로, 버전 관리되는 명세가 코드·테스트·문서를 파생시키는 근본 산출물이 되어야 한다고 주장한다. OpenAI Model Spec을 예로 들어 버전 관리되는 마크다운 명세의 각 조항이 까다로운 예시 프롬프트와 연결되어 성공 기준으로 작동하고, 심의적 정렬(deliberative alignment) 학습 루프에서 실행 가능한 정책이 된다고 설명한다. 명세의 모호함을 잡아내는 린터와 일관성 검사기, 작성 중 불명확한 표현을 드러내는 '통합 사고 명료화기'를 제안한다.

“code is sort of 10 to 20 percent of the value that you bring. The other 80 to 90 percent is in structured communication.”

프롬프트와 대화 속에 흩어져 사라지는 의도를 저장소에 남는 버전 관리 명세로 승격시켜야 한다는 주장이라, 의도 부채를 줄일 산출물이 무엇이어야 하는지 정할 때 기준이 된다. 명세 조항을 검증 가능한 예시와 연결하는 Model Spec 방식은 결정 근거를 테스트로 보존하는 구체적 사례다.

명세 주도 개발결정 기록(ADR)개념 틀과 이론

Birgitta Böckeler (Thoughtworks)martinfowler.com, Exploring Generative AI 시리즈기사영어

Thoughtworks의 Birgitta Böckeler가 2025년 10월 15일 Kiro, spec-kit, Tessl 세 SDD 도구를 같은 과제로 직접 써 보고 정리한 글로, spec-first(작업 전에 명세 작성)·spec-anchored(작업 후에도 명세를 유지해 기능 진화에 사용)·spec-as-source(사람은 명세만 편집하고 코드는 손대지 않음) 세 수준을 제안한다. Kiro는 작은 버그 하나를 4개 사용자 스토리·16개 수락 기준으로 부풀렸고, spec-kit은 명세 폴더 하나에 8개 파일을 만들어 "차라리 코드를 리뷰하겠다"는 평가를 받았으며, Tessl은 아직 베타로 명세 하나가 코드 파일 하나에 1:1 대응하는 단계라고 본다. 명세를 모든 세션에 적용되는 메모리 뱅크(맥락 파일)와 구분하고, "spec-driven development"라는 용어가 이미 의미가 희석됐으며 spec-as-source는 MDD의 경직성과 LLM의 비결정성을 동시에 떠안을 수 있다고 경고한다.

“These files are relevant across all AI coding sessions in the codebase, whereas specs only relevant to the tasks that actually create or change that particular functionality.”

세 SDD 도구를 같은 과제로 비교한 1차 실사용 리포트로, 명세가 의도를 코드 곁에 보존하는지 아니면 리뷰 부담만 늘리는지 판단할 기준과 어휘(spec-first/anchored/as-source, 명세 vs 메모리 뱅크 구분)를 제공한다.

명세 주도 개발이해 유지 실천개념 틀과 이론

Josh Devenny (Atlassian)Atlassian Blog (Announcements)블로그영어

Jira와 Confluence를 Claude, ChatGPT, Cursor, VS Code, Devin 같은 외부 AI 클라이언트에 MCP로 연결하는 Rovo MCP Server가 2026-02-04에 정식 출시됐다는 발표다. 제공 기능은 Jira·Confluence 의미 검색, Confluence 페이지 생성·갱신, Jira 에픽·이슈 생성·연결이다. 관리자는 연결할 수 있는 클라이언트를 제한하고 MCP 사용 로그를 볼 수 있다. 위키와 이슈 트래커에 쌓인 조직 지식을 AI 에이전트가 작업 중에 바로 읽고 다시 쓰게 하는 벤더의 공식 경로다.

“Connect your AI client to the Atlassian Rovo MCP Server, consent to scopes and sign in with an Atlassian account, and bring your context-rich Jira and Confluence work right to you.”

Confluence 기획서와 Jira 티켓을 SSOT로 쓰는 팀에서, 코딩 에이전트가 그 원문을 직접 읽고 갱신하게 하는 공식 연결 경로를 보여 준다.

조직 지식 검색강제 장치·기여 정책

Martin Vogel, Falk Meyer-Eschenbach, Severin Kohler, Elias Grünewald, Felix BalzerarXiv논문영어

LLM 코딩 에이전트가 파일 읽기와 grep을 반복하며 구조를 이해하지 못한 채 질의마다 수천 토큰을 쓴다는 문제에서 출발한 논문이다. 저자들은 tree-sitter로 66개 언어를 파싱해 영속적인 코드 지식 그래프를 만들고 이를 MCP로 제공하는 오픈소스 시스템 Codebase-Memory를 제안한다. 이 시스템은 호출 그래프 탐색, 영향 분석, 커뮤니티 탐지를 지원한다. 31개 실제 저장소에서 평가한 결과, 파일 탐색 에이전트보다 답 품질은 다소 낮지만 토큰과 도구 호출은 크게 줄었다고 보고한다.

“LLM coding agents typically explore codebases through repeated file-reading and grep-searching, consuming thousands of tokens per query without structural understanding.”

grep 기반 에이전틱 검색과 코드 지식 그래프 사이의 트레이드오프(답 품질 대 토큰 비용)를 수치로 보여 준다. 그래서 에이전트에게 어떤 검색 계층을 줄지 판단하는 근거가 된다. 다만 이 그래프가 담는 것은 코드의 구조 지식이며, 결정의 이유나 기각된 대안 같은 의도는 담지 않는다.

조직 지식 검색에이전트 메모리

AtlassianAtlassian Developer docs공식 문서영어

Atlassian의 Rovo MCP 서버는 Teamwork Graph를 통해 AI 에이전트를 Jira·Jira Service Management·Confluence·Bitbucket에 연결하는 공식 커넥터다. 에이전트는 이 서버로 요약·검색·콘텐츠 생성·자동화 같은 작업을 할 수 있다. 인증은 권장 방식인 OAuth 2.1과, 조직 관리자가 허용한 경우의 API 토큰 두 가지다. 모든 동작은 사용자의 기존 접근 권한을 그대로 따른다.

“All actions respect users' existing access controls and permissions.”

기획 정책은 Confluence에, 티켓 상태와 완료 조건은 Jira에 있다. 이 서버는 코딩 에이전트가 작업 전에 그 정본을 직접 조회하게 하는 공식 경로다. 따라서 정책을 어디서 읽을지 정하는 SSOT 규칙과 바로 결합할 수 있다.

조직 지식 검색

Evis Drenova (Entire)Entire blog블로그영어

Entire가 저장해 둔 에이전트 세션 로그와 커밋 히스토리, 코드를 에이전트가 검색할 수 있게 하는 기능을 발표한 글이다. 푸시 이벤트가 발생하면 커밋을 diff해 세션 로그와 커밋 메시지를 청크로 나눠 색인하므로, 에이전트는 특정 로직이 정의된 대화를 찾아 코드의 배경을 확인할 수 있다. 성능 수치는 벤더가 직접 측정한 결과다.

“If your agent searches for 'rate limit retry logic,' it will go through your session and commit history and find the conversation where the rate limit retry logic is defined.”

세션 기록을 저장하는 데서 그치지 않고 다음 에이전트가 검색으로 결정 맥락을 꺼내 쓰게 한 사례이며, 효과를 벤더 자체 수치로 제시한다.

조직 지식 검색커밋 히스토리·변경 출처에이전트 메모리측정과 실증

Jeremy Stribling / CursorCursor blog블로그영어

Cursor가 대규모 코드베이스의 의미 검색 색인을 같은 조직의 팀원끼리 안전하게 재사용하는 방식을 설명한 글이다. 파일과 디렉터리의 암호 해시로 이루어진 머클 트리로 바뀐 파일만 찾아내고, 바뀐 파일은 구문 단위 청크로 나눠 임베딩하며 임베딩은 내용 기준으로 캐시한다. 서버는 암호화된 경로마다 해시를 붙인 트리를 content proof로 보관하고, 클라이언트가 소유를 증명하지 못한 파일은 검색 결과에서 걸러 낸다. 의미 검색이 에이전트 성능의 가장 큰 동인 중 하나이며, 색인을 재사용하면 첫 질의까지 걸리는 시간이 크게 줄어든다고 보고한다.

“Semantic search is one of the biggest drivers of agent performance.”

에이전트에게 코드베이스 맥락을 주는 방법 가운데 임베딩 기반 의미 검색 색인 노선을 대표하는 2026년 벤더 근거다. 의미 검색이 에이전트 성능에 주는 효과를 수치로 제시하고, 팀 단위로 색인을 공유할 때의 보안 설계도 함께 보여 준다. 다만 이 글이 다루는 것은 코드 자체의 검색이며, 결정 이유나 버린 대안 같은 의도 정보를 다루지는 않는다.

조직 지식 검색

Dennis Pilarinos / UnblockedUnblocked blog블로그영어

Unblocked가 코드 저장소·Jira·Slack·Confluence·Notion의 엔지니어링 지식을 에이전트에 제공하는 컨텍스트 엔진을 발표한 글이다. 개편한 MCP 서버를 베타에서 정식으로 전환하고, 스크립트로 쓸 수 있는 CLI와 GitHub 스킬 쿡북을 함께 공개했다. 고객 인용에서는 Slack에 남은 아키텍처 결정 대화를 끌어오자 PR 리뷰 왕복이 세 번에서 한 번으로 줄었다고 소개한다. Kotlin SDK 모노레포 실험에서 Unblocked를 쓴 경우와 쓰지 않은 경우를 비교한 벤더 측 수치도 제시한다.

“When I plugged Unblocked into our context-gathering and PR review steps, it brought in the Slack conversations where real architectural decisions get made.”

Slack·Jira·Confluence에 흩어진 결정 근거를 MCP 서버로 코딩 에이전트에 넘기는 상용 컨텍스트 엔진의 사례로, 의도 부채를 검색·연결로 줄이려는 접근을 보여준다.

조직 지식 검색

Dennis Pilarinos (Unblocked)LeadDev London (LDX3) 2026 강연 정리, Unblocked 블로그 (2026-06-17)발표영어

LDX3 런던 강연을 Unblocked 블로그에 정리한 글이다. 코딩 에이전트는 팀이 왜 특정 기술을 골랐는지, Slack 스레드에서 무엇이 결정됐는지, 리뷰에서 어떤 아키텍처 패턴을 강제하는지 모른다고 진단한다. 해법으로 흩어진 조직 지식을 지속적으로 합성해 사람과 에이전트가 질의할 수 있게 하는 '컨텍스트 엔진'을 제안하고, '접근이 곧 이해는 아니다'라며 단순 RAG와 구분한다. 벤더 입장에서 쓴 글이다.

“They don't know why your team chose Redis over DynamoDB, what got decided in a Slack thread last night about the auth migration, or which architectural patterns your principal engineers actually enforce in review.”

결정의 '왜'가 코드가 아니라 Slack·리뷰 같은 대화 기록에 남아 있어 에이전트가 닿지 못한다는 문제를 짚고, 이를 모아 질의하게 하는 벤더 측 접근을 보여 준다.

조직 지식 검색강제 장치·기여 정책

신동걸, 심효진 (NAVER 플레이스 AI 추천)NAVER ENGINEERING DAY 2026 (D2 Hello world 공개)발표한국어

2026년 5월 NAVER ENGINEERING DAY에서 NAVER 플레이스 AI 추천 소속 발표자들이 발표한 세션을 D2에 영상과 소개문으로 공개한 것이다. '우리 팀의 AI Agent, 왜 엉뚱한 소리를 했나'라는 문제 제기에서 출발해 Agentic Context Platform과 Context Provider 구축 과정을 다룬다. 팀의 데이터·서빙 레이어 자산을 자동으로 수집해 제공하는 AI 플랫폼을 만들고 이를 통해 팀 업무를 효율화한 경험을 공유한다. 제목상 사람과 AI Agent가 함께 쓰는 통합 컨텍스트 공급원을 지향한다.

“팀 내 데이터/서빙 레이어 자산을 자동으로 수집하여 제공하는 AI 플랫폼 마련 및 이를 통한 팀 내 업무 효율화 경험을 공유합니다.”

에이전트가 엉뚱한 답을 내는 문제에서 출발해 팀 자산을 자동 수집하는 컨텍스트 공급원을 플랫폼으로 만든 국내 사례다. 컨텍스트 제공을 개인 프롬프트가 아닌 팀 인프라로 옮기려는 팀이 참고할 수 있다.

조직 지식 검색강제 장치·기여 정책

세바스찬, 올뤼버 (쏘카)쏘카 기술 블로그블로그한국어

AI 에이전트가 이미 있는 관리자 상태 변경 API를 알아보지 못하고 기능을 다시 만들어 반나절을 쓴 사고에서 출발한다. 흩어진 코드와 문서만으로는 에이전트가 기존 기능을 찾지 못한다고 보고, 개념·규칙·결정·코드를 노드로 하는 지식 그래프(parking-brain)를 Neo4j에 구축해 MCP로 사람과 AI가 같은 방식으로 질의하게 했다. 각 노드는 sourceRef로 원본 코드·티켓·문서를 가리키므로, 그래프는 새 진실 원본이 아니라 캐시이자 인덱스 역할을 한다. 갱신은 사람이 아니라 파이프라인이 맡는다.

“사람이 갱신하지 않습니다. 신선도를 사람의 성실함이 아니라 파이프라인에 맡깁니다.”

의도 부채의 대표 증상인 '이미 있는 기능을 AI가 다시 만드는 일'을 국내 회사가 직접 겪은 1차 사례다. 코드에 없는 의도·정책·도메인 의미를 지식 그래프와 MCP로 에이전트에게 제공한 설계와 교훈을 그대로 참고할 수 있다.

조직 지식 검색결정 기록(ADR)강제 장치·기여 정책

ThoughtworksThoughtworks Technology Radar Vol. 34 (November 2025), Techniques, Assess보고서영어

정적인 프롬프트 예시 대신 실제로 컴파일되는 참조 애플리케이션을 두고 코딩 에이전트를 거기에 고정하는 기법을 소개한다. MCP 서버가 참조 템플릿 코드와 커밋 diff를 함께 노출해 에이전트가 드리프트를 감지하고 수정을 제안하게 한다. 정적 템플릿을 살아 있는 청사진으로 바꿔 시스템이 진화해도 일관성을 유지하고 발산을 줄인다는 것이 요지다.

“A Model Context Protocol (MCP) server exposes both reference template code and commit diffs, enabling agents to detect drift and propose repairs.”

팀이 합의한 패턴을 문서가 아니라 동작하는 참조 코드로 유지하고 에이전트 결과물을 거기에 비교해 드리프트를 잡는 방식으로, 의도가 코드 변경 과정에서 흩어지는 문제에 대한 실무 대응 사례다. 컴포넌트·페이지 표준을 참조 앱으로 두는 프런트엔드 팀에도 적용하기 쉽다.

조직 지식 검색강제 장치·기여 정책

DORA / Google Clouddora.dev (DORA AI Capabilities Model)공식 문서영어

DORA AI 역량 모델의 한 축인 'AI 접근 가능한 내부 데이터'를 설명하는 공식 문서다. 최신 API 문서·사내 정책·준수 코드 조각 같은 관련 정보를 자동으로 모아 워크플로를 관리하는 체계를 '컨텍스트 엔지니어링'이라 부르고, 내부 데이터에 접근하는 AI 도구가 개인 효율성과 코드 품질에 통계적으로 유의한 승수로 작용한다고 밝힌다. 도입 경로로는 재사용 가능한 컨텍스트 템플릿(브리핑 패킷)을 버전 관리하는 수동 단계, RAG·MCP 서버를 이용한 자동화 단계, 내부 API를 넓히는 확장 단계를 제시한다. 폐기된 프로젝트를 색인해 나쁜 습관을 학습시키는 것과 컨텍스트 과적재로 인한 'context rot'을 함정으로 꼽는다.

“DORA research confirms that giving teams AI tools that can access internal data directly amplifies the positive impact of AI adoption, serving as a statistically significant multiplier for individual effectiveness and code quality.”

CLAUDE.md 같은 브리핑 패킷을 버전 관리하고 RAG·MCP로 사내 문서와 결정 기록을 AI에 연결하라는 지침이 DORA 공식 문서에 명시되어 있다. 따라서 의도 부채 대응 방법론의 산업계 근거 문서로 쓸 수 있다.

조직 지식 검색저장소 지시 파일강제 장치·기여 정책측정과 실증

Boris Cherny, Cat Wu (Anthropic) / Latent SpaceLatent Space podcast발표영어

Claude Code 리드 엔지니어 Boris Cherny와 PM Cat Wu가 출연한 팟캐스트 인터뷰다. 초기 버전은 Voyage 임베딩으로 코드베이스를 색인하는 RAG를 썼으나, 결국 에이전트가 grep·glob 같은 일반 코드 검색 도구를 호출하는 '에이전틱 검색'으로 정착했다고 밝힌다. 에이전틱 검색이 성능에서 크게 앞섰고, 색인 방식은 코드와 색인이 어긋나는 문제와 보안 부담이 있어 토큰·지연 비용을 감수했다고 설명한다.

“Originally, we tried very, very early versions of Claude actually used RAG. So we, like, indexed the code base, and I think we were just using Voyage.”

가장 널리 쓰이는 코딩 에이전트 중 하나가 벡터 색인 대신 grep 기반 검색을 택한 이유를 1차 출처로 보여 준다. 사전 색인 없이 맥락을 찾는 에이전트라면 결정의 이유도 저장소 안에 검색 가능한 텍스트로 남아 있어야 한다는 점을 시사한다[추정: 이 함의는 인터뷰의 직접 주장이 아니다].

조직 지식 검색

Xin Peng, Chong WangarXiv preprint, vision paper (v1 2025-03-11, v4 2026-02-02, "continuously updated")논문영어

Cursor·Claude Code 같은 AI 코딩 도구가 기대는 컨텍스트 공학과 RAG는 초복잡 기업 시스템에서 한계에 부딪힌다고 진단한다. 이런 시스템은 설계 제약 아래 점진적으로 진화하며, 책임·의도·결정 근거 같은 암묵지가 코드·설정·논의·버전 이력에 흩어져 있기 때문이다. 이에 코드베이스 위에 구축되어 시스템과 함께 진화하는 지속적 지식 인프라 'Code Digital Twin'을 제안한다. 장기적 지식 공학을 작업 시점의 컨텍스트 공학과 분리하고 AI 코딩 도우미의 백엔드 '컨텍스트 엔진' 역할을 하는 비전 논문이다.

“the required context is scattered across artifacts and entangled across time, beyond the capacity of LLMs to reliably capture, prioritize, and fuse evidence into correct and trustworthy decisions”

작업할 때마다 코드를 검색해 컨텍스트를 모으는 일과, 의도·결정 근거를 따로 축적하고 갱신하는 장기 지식 공학을 구분해 준다. 이 구분은 팀 SSOT를 어느 층에 둘지 정하는 틀이 된다. 다만 실증 평가가 없는 비전 제안이다.

조직 지식 검색개념 틀과 이론결정 기록(ADR)

Sylvain Giuliani / Augment CodeAugment Code blog블로그영어

Augment Code가 Context Engine에 git 커밋 히스토리 색인(Context Lineage)을 추가했다고 발표한 글이다. 확장이 워크스페이스 파일과 함께 git 히스토리를 스캔하고 새 커밋을 거의 실시간으로 백엔드에 보낸다. Gemini 2.0 Flash가 각 커밋을 변경의 주 목적, 수정된 핵심 함수·파일, 검색에 도움이 되는 기술 용어를 담은 몇 문장으로 요약하고, 이 요약을 임베딩해 에이전트가 필요할 때 과거 커밋을 찾게 한다. 이렇게 해서 '왜 이 파라미터 이름을 바꿨나' 같은 질문에 커밋 히스토리로 답할 수 있게 한다.

“Raw diffs can be huge. Instead of embedding thousands of lines, we ask Gemini 2.0 Flash to condense each commit into a few sentences with:”

커밋 히스토리를 '왜'를 담은 저장소로 보고 색인하는 벤더 구현 사례다. 커밋에 담긴 변경 목적이 에이전트가 검색해 읽는 의도 기록이 된다는 점에서 의도 부채 완화와 직접 닿아 있다.

조직 지식 검색커밋 히스토리·변경 출처

GitHubGitHub Changelog블로그영어

GitHub이 코드·문서·노트 등을 한 공간(Space)에 모아 Copilot 답변의 근거로 삼는 Copilot Spaces를 발표한 글이다. 중요한 맥락이 코드, 문서, 팀원의 머릿속에 흩어져 있어 새 영역에 적응하기 어렵다는 문제를 제기한다. 추가 맥락을 받은 Copilot은 시스템이 어떻게 동작하는지뿐 아니라 왜 그렇게 만들어졌는지까지 이해하는 전문가가 된다고 설명한다. 커스텀 지시를 넣을 수 있고 조직 안에서 공유할 수도 있다.

“Having critical context scattered across code, documentation, and inside of team members' heads can make it hard to get up to speed in a new area and get things done.”

팀원의 머릿속에 흩어진 '왜'를 포함한 맥락을 공유 가능한 공간에 모아 AI에게 넘기려는 벤더 기능의 대표 사례다. 의도 부채를 도구 차원에서 줄이려는 접근을 보여 준다.

조직 지식 검색강제 장치·기여 정책

David Soria Parra (MCP Lead Core Maintainer)Model Context Protocol blog블로그영어

Model Context Protocol(MCP)이 Linux Foundation 산하에 새로 생긴 Agentic AI Foundation(AAIF)에 합류한다는 공식 발표다. 기존 유지관리자와 SEP 절차에 따른 거버넌스는 그대로 유지되고, Linux Foundation은 중립적인 거처와 인프라를 제공할 뿐 기술 방향은 정하지 않는다. MCP의 채택 규모를 수치로 밝히며, AGENTS.md와 goose도 AAIF의 창립 프로젝트로 함께 소개한다.

“For MCP little changes. The governance model we introduced earlier this year continues as is.”

에이전트에 외부 컨텍스트를 연결하는 MCP와 저장소 지시 파일 규격인 AGENTS.md가 같은 중립 재단 아래 표준으로 묶였다는 배경 자료다. 의도 기록을 에이전트에 전달하는 배관과 형식이 벤더 중립 표준으로 수렴하고 있음을 보여 준다. 다만 의도 기록 자체를 다루는 자료는 아니다.

조직 지식 검색저장소 지시 파일

Yicheng Tao, Yuante Li, Yao Qin, Yepang LiuarXiv논문영어

함수·파일 수준을 넘어 저장소 전체를 다뤄야 하는 저장소 수준 코드 생성(RLCG)에서 검색 증강 코드 생성(RACG)을 종합 정리한 서베이다. 이 논문은 RACG를 정적인 '검색 후 생성' 파이프라인이 아니라 컨텍스트 구성·검색 최적화·생성·환경 상호작용이 맞물린 과정으로 본다. 검색 기반(retrieval substrate)·제어 방식(control regime)·평가 설정을 아우르는 분석 틀로 그래프 기반·비그래프 기반 검색, 학습 기반 최적화, 자율 에이전트 구조를 분류한다. 2025년 10월에 처음 제출됐고 2026년 5월에 v3로 개정됐다.

“real-world software engineering requires reasoning over entire repositories, including cross-file dependencies, evolving execution environments, and global semantic consistency.”

코드 RAG와 그래프 검색 연구가 빠르게 늘어나는 가운데, 에이전트에 저장소 컨텍스트를 공급하는 기법에 어떤 계열이 있는지와 어떤 벤치마크로 평가되는지를 한 편으로 훑어볼 수 있는 출발점이다. 다만 이 논문이 다루는 것은 코드 구조 컨텍스트 검색이고, 결정의 이유(의도) 자체를 검색하는 문제는 직접 다루지 않는다.

조직 지식 검색개념 틀과 이론

Tobi Lütke (tobi)GitHub (MIT License)도구영어

마크다운 노트, 회의록, 문서, 지식 베이스를 로컬 기기에서 색인해 검색하는 CLI 검색 엔진이다. BM25 전문 검색과 벡터 의미 검색 결과를 RRF로 합친 뒤 LLM으로 재순위화하며, 모든 모델을 로컬에서 실행한다. `query`·`get`·`multi_get`·`status` 도구를 제공하는 MCP 서버를 내장하고 있어 코딩 에이전트가 문서를 직접 검색할 수 있다. 컬렉션과 경로에 설명(context)을 붙일 수 있고, 이 설명은 검색 결과와 함께 반환된다.

“An on-device search engine for everything you need to remember. Index your markdown notes, meeting transcripts, documentation, and knowledge bases.”

흩어진 결정 기록과 기획 문서를 클라우드 없이 로컬에서 색인하고, MCP로 AI 에이전트가 작업 전에 직접 검색하게 만드는 가벼운 검색 계층의 예다.

조직 지식 검색에이전트 메모리

Jiuang Zhao, Zitian Yang, Li Zhang, Xiaoli Lian, Donghao Yang, Xin Tan (Beihang University)ASE 2024 Research Papers (ACM SIGSOFT Distinguished Paper Award)논문영어

오픈소스 커뮤니티의 Jira 이슈 토론에 잠재된 설계 근거(설계 대안과 그것을 채택·기각한 논거)를 자동으로 캐내는 DRMiner를 제안한다. 개발자 이탈로 아키텍처가 필연적으로 침식되고, 즉각적 이득이 없어 설계 근거를 문서화할 동기가 부족하다는 문제의식에서 출발한다. 추출 문제를 여러 텍스트 분류 과제로 분해하고 LLM 프롬프트 튜닝과 휴리스틱 특징으로 풀며, 추출한 근거를 LLM에 제공하면 자동 프로그램 수리 성능이 크게 오르는 것을 보였다.

“With the turnover of developers, the architecture inevitably becomes eroded. However, there may be a lack of motivation for developers to document design rationales”

Jira 등 이슈 트래커에 이미 묻혀 있는 '왜'를 LLM으로 복원해 코딩 에이전트의 맥락으로 공급하는 방식이 실제로 효과가 있음을 실증한 근거로, 의도 부채를 사후 발굴로 갚는 접근의 대표 사례다.

조직 지식 검색커밋 히스토리·변경 출처결정 기록(ADR)

Jeremy Howard (Answer.AI)llmstxt.org (제안 사양 사이트)표준·규약영어

웹사이트에 /llms.txt라는 Markdown 파일을 두어 LLM과 에이전트가 추론 시점에 읽을 정보를 선별해 제공하자는 제안이다. HTML 페이지는 내비게이션·광고·JavaScript로 감싸여 있어 정제 텍스트로 되돌리기 어렵고, 컨텍스트 창은 여전히 사이트 전체를 담기에 작아 낭비되는 토큰이 시간과 비용을 쓴다는 문제의식에서 출발한다. H1 제목·요약 인용문·H2로 구분한 링크 목록이라는 고정 구조와 각 페이지의 .md 판 병행 제공을 권한다. 2024년 9월 3일 초판이 나왔고 2026년 8월 10일 v2로 갱신됐다.

“Agents are best served by concise, expert-level information gathered in a single, accessible location.”

사내 디자인 시스템이나 API 문서를 에이전트가 정확히 찾게 하려면 사람용 문서와 별개로 '에이전트용 목차'를 두어야 한다는 발상을 표준 형식으로 보여 준다.

조직 지식 검색강제 장치·기여 정책

한주연 (토스 Knowledge System Team Leader)Toss Tech (토스 기술 블로그)블로그한국어

토스 프론트엔드 챕터가 문서 탐색 부담과, 메신저 대화 속 지식이 사라지는 문제를 줄이려고 만든 두 도구를 소개한다. '박씨'는 기존 문서를 바탕으로 답하면서 출처를 함께 알려 주는 챗봇이고, IDE(VSCode, Cursor)와 사내 메신저에서 쓸 수 있다. '실록봇'은 대화 스레드에 이모지를 붙이거나 봇을 부르면 AI가 대화를 분석·요약해 문서 리포지토리에 PR을 올린다. 글에 따르면 두 도구를 쓴 뒤로 지식이 특정 팀원에게 몰리거나 같은 질문이 반복되는 문제가 줄었다.

“그런 대화가 메신저에서 일어나기 때문에 빠르게 휘발되고, 반복적으로 같은 질문이 올라오는 게 아쉬웠어요”

결정과 맥락이 메신저에서 사라지는 것은 의도 부채가 쌓이는 주요 경로다. 이 글은 그런 대화를 문서 PR로 되돌리는 자동화의 국내 사례이고, 사람과 AI가 참고할 문서 저장소를 키우는 방법이기도 하다.

조직 지식 검색강제 장치·기여 정책

aider project (aider.chat; author not listed on page)aider blog블로그영어

aider가 tree-sitter로 소스를 파싱해 클래스·메서드·함수 시그니처를 추린 '저장소 지도(repo map)'를 만드는 방식을 설명한 글이다. 파일을 노드로, 의존 관계를 간선으로 둔 그래프에 순위 알고리즘을 적용해 토큰 예산 안에 가장 관련 높은 부분만 담는다. 파일 전체를 넣지 않고도 코드가 저장소의 나머지와 어떻게 연결되는지 모델에 보여 주는 것이 목적이다. 구조적 관계는 압축하지만 결정의 이유는 담지 않는다.

“each source file is a node and edges connect files which have dependencies”

오픈소스 코딩 에이전트의 대표적인 '구조 압축' 컨텍스트 기법을 설명한 원문이다. 구조 지도만으로는 결정 이유가 복원되지 않는다는 점을 보여 주는 비교 기준이 된다.

조직 지식 검색

SourcegraphSourcegraph docs공식 문서영어

Deep Search는 코드베이스에 대한 자연어 질문을 받아 에이전트가 Sourcegraph의 코드 검색·코드 내비게이션 도구를 반복 호출하며 이해를 정제하고, 답과 함께 수행한 검색과 읽은 파일의 출처 목록을 돌려주는 에이전틱 코드 검색 기능이다. 검색 컨텍스트와 @-멘션으로 범위를 좁힐 수 있고, 조직 관례를 스킬과 AGENTS.md 형식 안내로 주입할 수 있으며, Sourcegraph API와 MCP 서버로 연동된다. 예시 프롬프트에 특정 기능이 마지막으로 바뀐 시점과 최근 커밋 diff를 설명하라는 요청이 있어, 변경 이력을 묻는 용도도 보여 준다.

“Every Deep Search response includes a detailed list of sources contributing to the answer. These sources show exactly which searches were performed and which files were read.”

여러 저장소 규모에서 코드가 언제 어떻게 바뀌었는지를 출처와 함께 답하게 하는 엔터프라이즈 검색 계층의 사례다. AGENTS.md 형식의 관례 주입이 코드 검색 도구에도 들어왔음을 보여 준다.

조직 지식 검색커밋 히스토리·변경 출처저장소 지시 파일

Tiferet Gazit (GitHub)The GitHub Blog블로그영어

GitHub가 2026년 1월 15일 공개한 글로, Copilot 에이전트형 기억 시스템의 설계와 평가를 다룬다. 에이전트는 작업 중 실행 가능한 통찰을 발견하면 도구를 호출해 기억을 만들고, 기억은 주제(subject)·사실(fact)·인용(citations)·근거(reason)로 구조화해 저장한다. 기억을 쓰기 직전에는 인용된 코드 위치를 현재 코드와 대조하는 실시간 검증으로 낡거나 잘못된 정보가 쓰이는 것을 막는다. 코드 리뷰 에이전트가 발견한 로깅 규약을 코딩 에이전트가 이어받는 식으로, 여러 에이전트가 저장소 범위의 기억을 공유한다.

“Instead of offline memory curation, we store memories with citations: references to specific code locations that support each fact.”

에이전트가 쌓는 저장소 공유 기억을 '코드 인용 + 사용 시점 재검증'으로 신뢰할 수 있게 만든 설계를 PR 병합률 같은 효과 수치와 함께 볼 수 있는 벤더 1차 자료다.

에이전트 메모리측정과 실증조직 지식 검색

Isabella He, AnthropicClaude Cookbook공식 문서영어

2026년 3월 20일 공개된 Claude Cookbook 문서로, 장기 실행 에이전트의 세 가지 컨텍스트 관리 기법인 컴팩션(compact_20260112), 도구 결과 삭제(clear_tool_uses_20250919), 메모리 도구(memory_20250818)를 같은 연구 과제(약 328,955토큰 코퍼스) 위에서 claude-sonnet-4-6으로 비교한다. 재요청 가능한 도구 결과가 문제면 삭제, 긴 대화·추론 누적이 문제면 컴팩션, 세션을 넘겨 지식을 보존해야 하면 메모리를 쓰라는 진단 프레임을 제시하고, Claude Code가 컴팩션과 두 가지 메모리 시스템을 병용한다고 밝힌다. 컴팩션 요약은 과제 핵심 사실은 남기지만 세부 수치는 잃으며, 메모리의 가치는 '무엇을 적을지에 대한 에이전트의 판단'에 달렸다고 서술한다.

“Memory's value depends on the agent's judgment about what to write.”

컴팩션이 기술적 결정을 잃지 않도록 요약 지시를 바꾸고 세션 간에는 메모리 파일에 판단을 기록하라는 API 수준의 구체적 지침으로, 에이전트가 의도를 어떻게 남기고 되찾는지를 수치로 보여준다.

에이전트 메모리측정과 실증

Thomas Dohmke / EntireEntire blog블로그영어

전 GitHub CEO Thomas Dohmke가 Entire 창업과 첫 기능 Checkpoints를 발표한 글이다. 에이전트 세션은 휘발성이라 프롬프트는 터미널에, 추론은 컨텍스트 창에 남아 있다가 세션을 닫는 순간 코드를 만든 결정·제약·반복 과정이 사라진다고 문제를 정의한다. 해법으로 트랜스크립트·프롬프트·수정한 파일·토큰 사용량·도구 호출을 버전 관리되는 데이터로 git 안에 자동 기록하자고 제안한다.

“Agent sessions are ephemeral. Prompts live in terminals and reasoning lives in context windows. The decisions, constraints, and iteration that produce code disappears the moment you close the session.”

AI 에이전트 세션에서 내린 결정의 맥락이 세션을 닫으면 사라진다는 문제를 업계 인물이 직접 정의한 1차 발표문이다. 그래서 의도 부채를 설명하는 출발점이자, git을 저장소로 삼는 해법의 대표 사례로 쓸 수 있다.

에이전트 메모리커밋 히스토리·변경 출처

Caleb Fahlgren 외 (Hugging Face)Hugging Face 블로그블로그영어

주석·문서·blame·위키·결정 로그처럼 맥락을 유지하는 수단은 모두 누군가 관리해야 하는데, 그 관리가 기능 개발에 밀리는 '접착 노동(glue work)'이라 지식이 사라진다고 진단하는 글이다. 에이전트가 코드베이스를 검색하고 여러 접근을 시도하며 오류를 만나고 문서를 읽고 방향을 바꾸는 과정을 담은 트레이스가 코드를 형성한 결정의 가장 밀도 높은 기록이라고 주장한다. 트레이스를 Hugging Face Buckets에 모아 에이전트가 과거 세션을 기억으로 참조하고, 트레이스 뷰어로 열어 보며, PR이 자신을 만든 트레이스에 링크하도록 제안한다.

“A PR can link back to the trace that produced it, so the next reviewer (human or agent) can see how the change actually came together.”

에이전트 세션 트레이스를 버리지 않고 저장해 PR에 연결하면, 따로 문서를 쓰지 않아도 '왜 이렇게 바꿨나'의 기록이 남는다는 실무 아이디어를 제공한다.

에이전트 메모리커밋 히스토리·변경 출처결정 기록(ADR)

Qizheng Zhang, Changran Hu, Shubhangi Upasani, Boyuan Ma, Fenglu Hong, Vamsidhar Kamanuru, Jay Rainton, Chen Wu, Mengmeng Ji, Hanchen Li, Urmish Thakker, James Zou, Kunle OlukotunarXiv (2510.04618) / ICLR 2026논문영어

2025년 10월 6일 arXiv에 공개되고 ICLR 2026에 채택된 논문이다. 가중치 갱신 대신 컨텍스트(지시·전략·근거)를 수정해 적응하는 기존 방식의 두 가지 실패를 지목한다. 간결화 편향(brevity bias)은 요약을 위해 도메인 통찰을 버리는 것이고, 컨텍스트 붕괴(context collapse)는 반복 재작성이 세부를 시간에 따라 침식하는 것이다. 이를 막기 위해 컨텍스트를 생성·반성·큐레이션 과정으로 축적·정제·정리되는 '진화하는 플레이북'으로 다루고, 구조화된 증분 갱신으로 세부 지식을 보존하는 ACE 프레임워크를 제안한다.

“Prior approaches improve usability but often suffer from brevity bias, which drops domain insights for concise summaries, and from context collapse, where iterative rewriting erodes details over time.”

요약·컴팩션 기반 컨텍스트 관리가 왜 결정의 세부를 잃는지(간결화 편향, 컨텍스트 붕괴)를 명명하고, 대안으로 증분 갱신되는 플레이북형 컨텍스트를 학술적으로 제시해 의도 부채 논의에 개념적 근거를 제공한다. 다만 소프트웨어 코드베이스의 설계 의도를 직접 다루는 논문은 아니며, 에이전트 메모리·시스템 프롬프트 최적화가 대상이다.

에이전트 메모리개념 틀과 이론측정과 실증

LangChainLangChain Blog기사영어

2025년 7월 2일 LangChain 팀이 발행한 개론으로, 컨텍스트 엔지니어링을 "다음 단계에 꼭 필요한 정보로 컨텍스트 창을 채우는 기술"로 정의하고 전략을 쓰기(write)·선택(select)·압축(compress)·격리(isolate) 네 범주로 체계화했다. 쓰기는 스크래치패드와 세션 간 장기 메모리(에피소드·절차·의미 기억), 선택은 Claude Code의 CLAUDE.md와 Cursor·Windsurf 규칙 파일, 임베딩·지식 그래프 기반 메모리 검색과 RAG 도구 선택, 압축은 요약과 트리밍(Claude Code auto-compact 포함), 격리는 멀티에이전트·샌드박스·상태 객체를 예로 든다. 의도 부채 대응책을 분류할 때 널리 인용되는 공용 프레임이다.

“The delicate art and science of filling the context window with just the right information for the next step.”

팀의 결정 기록·규칙 파일·메모리를 쓰기/선택/압축/격리 중 어느 축에 둘지 판단하는 공용 어휘를 제공하며, CLAUDE.md 같은 저장소 지침 파일을 에이전트의 절차적 메모리로 자리매김한다.

에이전트 메모리조직 지식 검색저장소 지시 파일개념 틀과 이론

Yichao 'Peak' Ji (Manus)Manus blog블로그영어

2025년 7월 18일 Manus 공동창업자 Yichao 'Peak' Ji가 에이전트 컨텍스트 설계에서 얻은 여섯 가지 실전 교훈을 정리한 글이다. KV 캐시 적중률 중심 설계, 도구를 제거하지 않고 마스킹하기, 파일 시스템을 구조화된 외부 기억으로 쓰기, todo.md를 반복 갱신해 목표를 최근 주의 범위에 두기, 실패 흔적을 컨텍스트에 남기기, 반복 패턴(few-shot)에 대한 경계를 다룬다. 파일을 외부 기억으로 쓰고 실수를 지우지 않는다는 원칙은 '무엇을 시도했고 왜 실패했는가'를 보존하려는 의도 부채 대응과 맞닿아 있다.

“Erasing failure removes evidence. And without evidence, the model can't adapt.”

레포 안 마크다운 파일을 에이전트의 장기 기억으로 쓰고, 시도·실패 기록을 지우지 않는 실무 패턴의 근거로 쓸 수 있다. 다만 코드베이스 의도 보존이 아니라 범용 에이전트 컨텍스트 설계를 다룬 글이므로 간접 근거로 인용한다.

에이전트 메모리개념 틀과 이론

Cursor (Anysphere)Cursor Changelog공식 문서영어

Cursor는 2025년 6월 4일 1.0 릴리스에서 대화 속 사실을 기억했다가 나중에 참조하는 Memories 기능을 베타로 도입했다. 기억은 '프로젝트별로, 개인 단위로' 저장되고 설정에서 관리하며, Settings → Rules에서 켠다. 변경 기록은 팀 공유를 따로 다루지 않는다. 다만 개인 단위로 저장된다는 점에서, 에이전트가 배운 결정은 팀 공용 규칙 파일로 옮기지 않는 한 개인에게만 남는다고 읽을 수 있다.

“With Memories, Cursor can remember facts from conversations and reference them in the future. Memories are stored per project on an individual level, and can be managed from Settings.”

Cursor를 쓰는 팀이라면 자동 기억이 개인 단위라는 점을 알아야 한다. 그래야 팀이 합의한 결정을 저장소의 공용 규칙으로 옮기는 절차를 따로 만들 수 있다.

에이전트 메모리

Anthropic Applied AI (Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, Jeremy Hadfield; 기여 Rafi Ayub, Hannah Moran, Cal Rueb, Connor Jennings)Anthropic Engineering기사영어

2025년 9월 29일 게재된 글로, 컨텍스트 엔지니어링을 'LLM 추론 중 최적의 토큰(정보) 집합을 선별·유지하는 전략의 집합'으로 정의하고 프롬프트 엔지니어링의 자연스러운 진화로 자리매김한다. LLM에는 사람의 작업 기억처럼 유한한 주의 예산(attention budget)이 있고 컨텍스트가 길어질수록 회상 정확도가 떨어지는 컨텍스트 부패(context rot)가 생긴다고 설명한다. 이에 대한 기법으로 파일 경로·URL 같은 경량 식별자만 두고 런타임에 도구로 읽는 just-in-time 검색, 컴팩션, NOTES.md 같은 구조화된 노트 작성, 요약만 반환하는 서브에이전트 아키텍처를 제시한다. Claude Code는 CLAUDE.md를 사전 로드하고 glob·grep으로 런타임 탐색하는 하이브리드 모델의 예로 언급된다.

“Claude Code is an agent that employs this hybrid model: CLAUDE.md files are naively dropped into context up front, while primitives like glob and grep allow it to navigate its environment and retrieve files just-in-time”

코딩 에이전트에 프로젝트 의도를 전달하는 방식으로 CLAUDE.md 사전 로드 + 필요 시 탐색 + 노트 파일의 조합을 도구 제작사가 공식적으로 권고한 1차 출처다. 의도 부채 해결책 중 '컨텍스트 엔지니어링' 계열의 개념 정의와 용어(attention budget, context rot, compaction)를 인용할 때 근거로 쓸 수 있다.

에이전트 메모리조직 지식 검색저장소 지시 파일개념 틀과 이론

Prateek Chhikara, Dev Khant, Saket Aryan, Taranjeet Singh, Deshraj Yadav (Mem0)arXiv (2504.19413)논문영어

2025년 4월 28일 arXiv에 공개된 논문이다. 다중 세션 대화에서 핵심 정보를 동적으로 추출·통합·검색하는 메모리 중심 아키텍처 Mem0와, 요소 간 관계 구조를 담는 그래프 기반 변형을 제안하고 LOCOMO 벤치마크에서 여섯 범주의 베이스라인(메모리 증강 시스템, RAG, 전체 컨텍스트, 오픈소스 메모리, 독점 모델, 메모리 관리 플랫폼)과 비교했다. 초점은 코드베이스가 아니라 대화 메모리지만, 전체 대화 히스토리를 넣는 대신 선별 메모리를 쓰면 지연과 토큰 비용이 크게 줄어든다는 정량 근거를 제공한다.

“In particular, Mem0 attains a 91% lower p95 latency and saves more than 90% token cost, offering a compelling balance between advanced reasoning capabilities and practical deployment constraints.”

'히스토리 전체를 컨텍스트에 넣기'와 '선별된 장기 메모리'의 비용·지연 차이를 수치로 설득할 때 쓸 수 있다. 다만 대상이 대화 메모리이므로 코드베이스 의도 보존에 직접 적용한 결과로 인용해서는 안 된다.

에이전트 메모리측정과 실증

SpecStoryGitHub도구영어

SpecStory의 IDE 확장과 CLI의 설치 방법과 저장 구조를 설명한 README다. 확장과 CLI는 모든 AI 대화를 프로젝트의 .specstory/history/에 로컬 우선으로 저장하고, 사용자가 명시적으로 로그인했을 때만 클라우드로 동기화한다. 같은 저장소에는 저장된 세션을 근거 기반 에이전트 스킬로 가공하는 Lore도 소개돼 있어, 대화 기록을 다음 에이전트가 쓸 수 있는 능력으로 되돌리는 흐름을 다룬다.

“Extensions save every AI interaction locally to `.specstory/history/`”

에이전트와 나눈 대화 기록이 저장소의 어느 경로에 남는지 구체적으로 보여 준다. 그래서 대화 기록을 커밋할지(.gitignore 정책), 리뷰 대상에 넣을지 팀이 정할 때 참고가 된다. 또 대화에 담긴 의도를 다음 에이전트용 스킬로 되살리는 접근의 사례다.

에이전트 메모리조직 지식 검색

Charles Packer, Sarah Wooders, Kevin Lin, Vivian Fang, Shishir G. Patil, Ion Stoica, Joseph E. GonzalezarXiv논문영어

2023년 10월 arXiv에 공개되고 2024년 2월 v2로 갱신된 논문이다. 운영체제의 계층적 메모리에서 착안한 '가상 컨텍스트 관리(virtual context management)'를 제안해, 제한된 컨텍스트 창 안에서 빠른 메모리와 느린 메모리 사이에 데이터를 옮기고 인터럽트로 사용자와의 제어 흐름을 다루는 시스템 MemGPT를 소개한다. 컨텍스트 창을 훨씬 넘는 대용량 문서 분석과 다중 세션 채팅 두 도메인에서 평가하며, 장기 상호작용을 거쳐 '기억하고 반성하고 진화'하는 대화 에이전트를 만들 수 있다고 주장한다. 코드와 데이터는 memgpt.ai에서 공개했다.

“we propose virtual context management, a technique drawing inspiration from hierarchical memory systems in traditional operating systems that provide the appearance of large memory resources”

세션을 넘어 지속되는 에이전트 메모리를 컨텍스트 창 밖의 계층 저장소로 설계한 초기 대표 연구로, 코딩 에이전트가 프로젝트의 의도와 결정 이력을 세션 간에 유지하는 방안을 논할 때 기준 문헌으로 인용할 수 있다. 다만 소프트웨어 개발이나 코드베이스 의도를 직접 다루지는 않는다.

에이전트 메모리개념 틀과 이론

GitHubGitHub Docs공식 문서영어

Copilot Memory는 저장소 수준 사실과 사용자 수준 선호라는 두 층으로 기억을 저장하는 기능이며, 현재 공개 프리뷰 단계다. 저장소 사실은 코딩 규칙, 아키텍처 결정, 빌드 명령, 프로젝트별 규칙을 다루고, 뒷받침하는 코드를 가리키는 인용과 함께 저장된다. Copilot은 관련이 있을 때 이 인용을 현재 브랜치와 대조하고, 검증된 사실만 사용한다. 쓰이지 않은 기억은 28일 뒤 자동 삭제되며, 저장소 소유자는 저장소 사실을 검토하고 직접 삭제할 수 있다.

“When relevant, Copilot checks those citations against the current branch to confirm the information is still accurate. Only validated facts are used.”

에이전트가 쌓는 팀 공유 기억에 코드 인용 검증과 28일 만료를 붙여 낡은 정보를 걸러내는 설계다. 이 설계는 팀의 결정 기록에도 근거 링크와 재검증 주기를 두는 방법을 보여 준다.

에이전트 메모리강제 장치·기여 정책

AnthropicClaude Code Docs공식 문서영어

Claude Code 서브에이전트에 memory frontmatter 필드를 지정하면, 서브에이전트가 대화가 끝나도 남는 기억 디렉터리에 코드베이스 패턴, 디버깅 요령, 아키텍처 결정 같은 지식을 쌓는다. 범위는 user, project, local 세 가지다. 이 가운데 project 범위는 저장소 안 .claude/agent-memory/<agent>/에 저장되어 버전 관리로 공유할 수 있고, 문서는 이것을 권장 기본값으로 제시한다. 서브에이전트 기억은 auto memory 기능의 일부라서 auto memory를 끄면 동작하지 않는다.

“`project` is the recommended default scope. It makes subagent knowledge shareable via version control.”

리뷰 에이전트 같은 서브에이전트가 쌓은 규약과 아키텍처 결정 기억을 저장소에 커밋하면, 팀이 이를 PR로 검토하고 공유할 수 있다. 에이전트 기억을 팀의 공식 지식으로 올리는 구체적인 방법이다.

에이전트 메모리강제 장치·기여 정책

Devin (Cognition)Devin Docs공식 문서영어

Devin의 Knowledge는 조직 범위의 지식 항목으로, 조직 구성원 모두에게 보인다. 엔터프라이즈 계정에서는 여러 조직에 걸친 엔터프라이즈 수준 지식으로 코딩 표준, 아키텍처 지침, 배포 절차를 공유할 수 있다. 항목은 저장소 없음, 특정 저장소, 모든 저장소 중 하나에 고정할 수 있고, Trigger Description으로 관련 작업일 때 불러온다. Devin은 채팅 피드백을 바탕으로 기억할 지식을 자동 제안하며, 사용자는 제안을 수정하거나 기각하거나 다시 생성하게 할 수 있다.

“Devin will automatically suggest Knowledge to remember based on your feedback in chat”

에이전트가 채팅 피드백에서 기억할 지식을 제안하고, 사람이 수정하거나 기각한 뒤 조직 전체에 공유하는 흐름이다. 팀원마다 다른 프로젝트 지식을 에이전트가 쓸 수 있게 모으는 참고 모델이 된다.

에이전트 메모리조직 지식 검색강제 장치·기여 정책

CodeRabbitCodeRabbit Docs공식 문서영어

CodeRabbit이 채팅 상호작용에서 팀의 코드 리뷰 선호를 학습해 Git 조직 단위 내부 데이터베이스에 'Learnings'로 저장하고 이후 리뷰에 적용하는 기능을 설명한다. 문서는 제안에 답할 때 이유('why')를 함께 적으면 비슷하지만 똑같지는 않은 상황에도 학습을 올바르게 적용하는 데 도움이 된다고 안내한다. 저장된 학습은 PR·이슈 댓글을 달기 전에 범위 설정에 따라 로드되고, 변경된 코드와 관련 있을 때만 적용된다. 리뷰 중에 말로만 남던 팀의 판단을 리뷰 봇의 지속 기억으로 옮기는 장치다.

“The 'why' helps CodeRabbit apply the learning correctly in similar-but-not-identical situations.”

리뷰에서 반복되는 팀의 결정과 그 이유를 봇의 지속 기억으로 쌓고 관리하는 방식을 구체적으로 문서화한 벤더 사례다.

에이전트 메모리강제 장치·기여 정책

OpenAIChatGPT / Codex documentation (redirected from developers.openai.com/codex/memories)공식 문서영어

Codex 로컬 메모리는 이전 대화를 바탕으로 백그라운드에서 만들어져 ~/.codex/memories/에 요약·지속 항목·최근 입력·근거 형태로 저장되는 사용자 단위 회상 계층이다. 기본값은 꺼져 있고, 진행 중이거나 짧은 세션은 요약하지 않으며, 생성된 기억 필드에서 비밀 정보를 가린다. 문서는 반드시 적용해야 할 팀 지침은 AGENTS.md나 체크인된 문서에 두고 메모리는 보조 회상 계층으로만 쓰라고 권고한다.

“Keep required team guidance in AGENTS.md or checked-in documentation. Treat memories as a helpful recall layer, not as the only source for rules that must always apply.”

자동 에이전트 메모리는 개인·로컬 보조 계층이고 팀이 지켜야 할 규칙의 정본은 AGENTS.md나 체크인된 문서라고 벤더가 직접 역할을 나눈 사례다. 의도를 어디에 기록해야 다음 사람이나 에이전트가 찾을 수 있는지 논할 때 근거로 쓸 수 있다.

에이전트 메모리저장소 지시 파일

GreptileGreptile Docs공식 문서영어

Greptile의 코드 리뷰 메모리는 PR에 달린 팀 댓글, Greptile 제안에 대한 답글, 👍/👎 반응, 그리고 첫 커밋과 마지막 커밋을 비교해 어떤 지적이 반영됐는지 분석하는 방식으로 팀 선호를 학습한다. 팀이 반복해 남기는 'Move DB calls to service layer' 같은 댓글에서 'Controllers should not contain direct database calls' 같은 규칙을 수동 설정 없이 추론하고, 규칙이 어떤 코드 영역에 적용되고 어디에는 적용되지 않는지도 학습한다고 설명한다. 명시적 문서가 없어도 리뷰 행동에서 팀의 의도를 끌어내는 접근이다.

“Greptile automatically infers custom rules from team behavior without manual configuration.”

팀 결정을 문서로 남기지 않아도 리뷰 반응에서 규칙을 뽑아내는 방식을 보여 준다. 이 방식의 가능성과 함께, 효과 근거가 벤더 수치뿐이라는 한계도 확인할 수 있다.

에이전트 메모리강제 장치·기여 정책

SpecStorydocs.specstory.com공식 문서영어

SpecStory는 스스로를 현대 소프트웨어 개발의 '의도 계층(intent layer)'이라고 소개하며, 이 문서는 그 공식 문서다. 여러 도구에서 AI와 나눈 대화를 깔끔한 마크다운으로 자동 저장하고, 그 히스토리를 코드와 함께 저장소 안에 두는 방식을 설명한다. 'Git은 코드에서 무엇이 바뀌었는지를 해결했고 SpecStory는 왜 바뀌었는지를 해결한다'고 포지셔닝한다.

“Git solved what changed in code. SpecStory solves why it changed.”

에이전트와의 대화 자체를 '왜'의 기록으로 저장소에 남기는 단순한 접근이라, 별도 인프라 없이 팀 저장소에서 바로 시험해 볼 수 있는 선택지다.

에이전트 메모리커밋 히스토리·변경 출처

Cursor, with contributors Amp, Amplitude, Cline, Cloudflare, Cognition, git-ai, Jules, OpenCode, Tapes, Vercelagent-trace.dev표준·규약영어

버전 관리 저장소의 코드 가운데 어느 부분이 AI에서 왔고 어느 부분을 사람이 썼는지 기록하기 위한 벤더 중립 JSON 형식을 제안한 공개 명세다. 트레이스 레코드는 파일별 줄 범위를 대화와 기여자 유형(human, ai, mixed, unknown)에 연결하고, 모델은 models.dev 규칙(provider/model-name)으로 식별한다. 저장 방식은 로컬 파일, git notes, 데이터베이스 등 구현에 맡기며, 호환 도구라면 어느 것이든 출처 데이터를 읽고 쓸 수 있게 하는 것을 목표로 한다.

“As agents write more code, it's important to understand what came from AI versus humans.”

도구마다 흩어진 AI 기여 출처 기록을 하나의 교환 형식으로 모으려는 여러 업체의 공동 명세라, 특정 벤더에 묶이지 않고 코드 변경의 출처와 대화 맥락을 남기는 방법을 고를 때 기준점이 된다.

커밋 히스토리·변경 출처

EntireGitHub도구영어

Entire CLI는 git 워크플로에 훅을 걸어 AI 에이전트 세션을 기록하고, 이를 커밋과 함께 색인해 코드가 어떻게 작성됐는지 검색할 수 있게 하는 오픈소스 도구다. 커밋에 `Entire-Checkpoint: <id>` 트레일러를 달고, 체크포인트는 브랜치 히스토리 밖의 개별 git ref(refs/entire/checkpoints/<shard>/<id>)에 저장한다. 이 ref가 가리키는 커밋 트리에 metadata.json, 세션별 트랜스크립트, 서브에이전트 작업 기록이 들어간다. 작업 중인 내용은 단명 섀도 브랜치에 두었다가 커밋할 때 영구 체크포인트로 압축하며, git for-each-ref나 entire checkpoint explain으로 조회할 수 있다.

“Checkpoints are created when you or the agent make a git commit, and the commit carries an `Entire-Checkpoint: <id>` trailer linking the two.”

에이전트 세션을 git notes가 아니라 커밋 트레일러와 별도 ref로 커밋에 묶는 구체적인 저장 형식을 보여 준다. 그래서 '이 변경이 어떤 대화에서 나왔나'를 되짚는 구현 사례가 되고, 팀 저장소에 도입할 때 push/fetch 설정과 용량 부담을 가늠하는 기준으로 쓸 수 있다.

커밋 히스토리·변경 출처에이전트 메모리

Daichi Furiya (wasabeef)DEV Community도구영어

AI 에이전트 세션의 프롬프트·응답·변경 파일·AI 비율을 커밋에 붙여 보존하는 오픈소스 도구 Agent Note의 소개 글이다. 세션 데이터는 `.git/agentnote/`에 임시로 저장하고, 영구 기록은 git notes `refs/notes/agentnote`에 둔다. 커밋 diff는 건드리지 않고 커밋 메시지에 짧은 세션 trailer만 추가한다. `agent-note why`는 git blame으로 대상 줄의 커밋을 찾은 뒤 그 커밋에 붙은 대화 기록을 보여준다.

“A diff tells you what changed. It does not tell you why it changed.”

Claude Code나 Cursor 대화가 세션이 끝나면 사라지는 팀이 대화를 커밋에 묶어 두고 싶을 때 참고할 만하다. git notes를 쓰기 때문에 diff와 기존 커밋 흐름을 거의 바꾸지 않고, 코드 줄에서 그 줄을 만든 "왜"를 거꾸로 찾아갈 수 있다.

커밋 히스토리·변경 출처에이전트 메모리

Mehedi Sun, Antu Saha, Nadeeshan De Silva, Antonio Mastropaolo, Oscar ChaparroarXiv (cs.SE)논문영어

과거 코드 변경의 근거(rationale)가 커밋 메시지·PR·이슈 등 여러 산출물에 흩어져 있다는 점을 실증하고, 흩어진 근거를 LLM으로 찾아 요약하는 ARGUS를 제안한 2026년 논문이다. 오픈소스 Java 5개 프로젝트의 커밋 63건을 기존 분류 체계의 9개 근거 요소로 추적한 결과, GOAL은 주로 커밋 메시지와 PR에, NEED와 ALTERNATIVE는 이슈와 PR에 나타났으며 어떤 단일 산출물 유형도 모든 요소를 일관되게 담지 못했다. ARGUS는 GOAL·NEED·ALTERNATIVE 문장 식별에서 전체 정밀도 51.4%, 재현율 93.2%를 기록했다. Java 프로그래머 12명은 생성된 요약이 낯선 코드 변경을 이해하고 코드 리뷰·문서화·디버깅·유지보수를 하는 데 유용하다고 평가했다.

“code change rationale is often fragmented, inconsistently documented, and scattered across heterogeneous artifacts.”

변경 이유가 커밋·PR·이슈에 흩어져 있어 한 곳만 봐서는 복원할 수 없음을 데이터로 보인 연구다. 에이전트가 이슈 트래커와 PR을 함께 읽어 "왜"를 모아야 한다는 근거가 되며, 무엇을 모아야 하는지(GOAL·NEED·ALTERNATIVE)의 기준도 된다.

커밋 히스토리·변경 출처결정 기록(ADR)조직 지식 검색측정과 실증

코비(covypark), 당근 중고거래실 구매팀 서버 엔지니어당근 테크 블로그 (Medium)블로그한국어

'이 기능 언제 나갔어요?'라는 질문마다 git log와 PR을 뒤져야 하는 비용을, 배포 내역의 맥락이 개발자 안에만 갇혀 있어 생기는 팀 전체의 커뮤니케이션 비용으로 규정한다. 배포 시점에 rake task가 git log에서 PR 목록을 파싱하고 gh CLI로 PR description을 모아 Notion(배포 DB·PR DB·LLM 릴리즈 노트 DB)에 적재한다. 매일 CronJob이 사내 Prompt Studio를 거쳐 비개발자도 읽을 수 있는 릴리즈 노트를 생성한다. diff 대신 CodeRabbit이 자동 요약한 PR description을 LLM 입력으로 쓰는 것이 핵심 결정이다.

“배포 내역의 맥락이 개발자 안에만 갇혀 있다는 게, 한 명의 불편이 아니라 팀 전체의 커뮤니케이션 비용을 발생시키는 문제였어요.”

변경 이력의 '언제'와 '무엇이 바뀌었나'를 개발자 머릿속에서 꺼내 팀 자산으로 쌓는 국내 사례다. PR description을 정제된 원문으로 삼고, 그 자산을 다시 코딩 에이전트(Claude Code 스킬)의 맥락으로 쓰는 흐름을 보여준다.

커밋 히스토리·변경 출처강제 장치·기여 정책조직 지식 검색

Git AI projectGitHub (git-ai-project/git-ai specs)표준·규약영어

git notes로 커밋에 AI 작성 이력(Authorship Log)을 붙이는 형식을 RFC 2119 용어로 규정한 공개 명세다. 로그는 파일별 줄 범위를 AI 세션이나 확인된 사람에게 연결하는 attestation 부분과, 프롬프트 기록·세션 정보·스키마 버전을 담은 JSON 메타데이터 부분으로 나뉜다. 어떤 키에도 속하지 않는 줄은 'untracked'로 두어 출처 데이터가 없다고 표시한다. 다른 도구도 같은 방식으로 git notes에 로그를 붙이면 준수 구현으로 본다고 명시한다.

“Authorship logs provide a record of which lines in a commit were authored by AI agents, along with the conversation threads that generated them.”

어떤 줄을 어느 AI 세션이 어떤 대화로 썼는지 커밋에 남기므로, 나중에 코드를 고치는 사람이나 에이전트가 변경의 출처를 되짚을 단서가 된다. 자체 훅이나 사내 도구를 만들 때 이 필드 형식을 따르면 표준과 호환되게 설계할 수 있다.

커밋 히스토리·변경 출처

Git AI project (maintainers Aidan Cunniffe, Sasha Varlamov)GitHub도구영어

git-ai는 AI가 쓴 코드 한 줄 한 줄을 그 줄을 만든 에이전트·모델·프롬프트와 연결하는 오픈소스 git 확장이다. README는 이를 통해 코드 뒤의 의도·요구사항·아키텍처 결정을 잃지 않게 한다고 설명한다. 코딩 에이전트가 자기가 쓴 줄을 직접 보고하며, 줄 단위 귀속 데이터는 Git Notes(refs/notes/ai)에 붙는다. 프롬프트 세션은 스캔·마스킹한 뒤 git 밖에 저장해 비밀정보 유출을 막고 접근 권한을 세밀하게 관리하며, git blame을 대체하는 AI blame을 제공한다.

“every line of AI code is linked to the agent, model, and prompts that generated it — so you never lose the intent, requirements, and architecture decisions behind your code.”

git blame 흐름은 그대로 두면서 AI가 쓴 줄과 그 줄을 만든 프롬프트를 되짚을 수 있다. 그래서 코드 리뷰 때나 레거시 코드를 고치기 전에 원래 의도를 확인하는 도구로 바로 시험해 볼 수 있다.

커밋 히스토리·변경 출처측정과 실증

GitKraken (GitLens for VS Code)GitKraken Help Center공식 문서영어

VS Code 확장 GitLens의 공식 기능 문서다. 현재 줄에 작성자·날짜·커밋 메시지를 표시하는 Current Line Blame, 커밋 상세와 이슈 자동 링크를 보여 주는 Details Hover, 이전 버전을 보여 주는 Changes Hover를 설명한다. 파일 변경의 작성자·크기·시점을 추적하는 Visual File History와 Commit Graph도 소개한다. Pro 이상 요금제에서는 AI Commit Explanations가 커밋의 목적과 맥락을 AI로 요약하고, Explain 기능(프리뷰)은 브랜치·작업 변경·stash를 마크다운으로 요약한다.

“Understand the purpose and context of commits with AI-generated summaries”

편집기 안에서 blame, 히스토리, AI 커밋 설명을 바로 보여 주는 도구다. 커밋 메시지에 남긴 "왜"를 다음 편집자가 실제로 읽게 만드는 소비 측 도구의 예다.

커밋 히스토리·변경 출처조직 지식 검색

Mouna Dhaouadi, Bentley James Oakes, Michalis Famelis (DIRO, Université de Montréal; GIGL, Polytechnique Montréal)ICPC 2024 — 32nd IEEE/ACM International Conference on Program Comprehension, Lisbon (DOI 10.1145/3643916.3644413)논문영어

리눅스 커널 OOM Killer 컴포넌트의 커밋 메시지를 문장 단위로 결정(Decision)·근거(Rationale)·보조 사실(Supporting Facts)로 라벨링한 데이터셋을 만들고, 근거의 존재 여부·영향 요인·시간적 변화·구조를 분석했다. 커밋 메시지는 개발자가 왜 변경했는지를 담는 원천이며, 이후 기여자가 시스템의 현재 상태를 만든 결정의 근거를 파악해야 한다는 문제의식에서 출발한다. 라벨링 과정의 난점과 예시도 함께 보고한다. 같은 저자들의 후속 연구(arXiv 2506.11005, 2025)는 Kantara 아키텍처 위에 사전학습 모델과 LLM을 얹어 결정·근거 문장을 자동 추출하고, 새 변경이 과거 결정과 충돌하는지 탐지하는 데까지 확장했다.

“We find that 98.9% of commits in our dataset contain sentences with rationale information, and that experienced developers report rationale in about 60% of the sentences in their commits.”

성숙한 오픈소스 프로젝트의 커밋 메시지에 '왜'가 실제로 얼마나 담기는지 정량화한 기준선이며, 커밋 로그에서 근거를 자동 복원하고 새 변경이 과거 결정과 충돌하는지 검사하는 도구 연구의 출발점이다.

커밋 히스토리·변경 출처측정과 실증

Yingchen Tian, Yuxia Zhang, Klaas-Jan Stol, Lin Jiang, Hui LiuICSE 2022 (DOI 10.1145/3510003.3510205), arXiv:2202.02974논문영어

커밋 메시지를 코드가 어떻게, 왜 바뀌었는지 이해하게 해 주는 "감사 추적(audit trail)"으로 보고, 무엇이 좋은 커밋 메시지인지를 정의한 ICSE 2022 논문이다. 활발한 오픈소스 5개 프로젝트에서 약 1,600건의 메시지를 표본으로 분석해 평균 약 44%가 정보가 부족해 개선될 수 있다고 보고한다. 이런 저품질 메시지가 걸러지지 않은 데이터셋으로 커밋 메시지 자동 생성기를 학습시키는 것이 큰 위협이라고 지적하고, 반복되는 표현 패턴에 기반한 분류 체계와 좋은 메시지를 자동 판별해 개발자에게 보완을 유도하는 방법을 제안한다.

“commit messages serve as an "audit trail" by which developers can understand how the source code of a project has changed-and why. Hence, the quality of commit messages affects the effectiveness of communication among developers.”

git 히스토리에서 '왜'를 복원하려는 팀이 커밋 메시지 규약을 세울 때 근거로 삼을 수 있는 대표적 실증 연구다. 실제 히스토리의 상당수가 의도를 담지 못한다는 정량 결과와, 그런 히스토리로 학습한 AI 생성기가 문제를 재생산한다는 지적은 의도 부채가 축적되는 경로를 보여준다.

커밋 히스토리·변경 출처측정과 실증

Joel Chippindale (FutureLearn CTO)LeadDev London 2016 (발표 원고, Mocoso 블로그)발표영어

2016년 LeadDev London 발표 원고로, 커밋 히스토리가 영구히 보존되고 항상 최신이며 검색 가능하다는 점에서 코드의 의도를 기록하는 데 특히 가치 있는 문서라고 주장한다. 실천 방법으로 원자적 커밋(메시지에 "and"가 필요하면 쪼갠다), 좋은 커밋 메시지(맥락과 검토한 대안, 이슈 트래커 링크 포함), 공유 전 interactive rebase로 개발 히스토리를 다듬기를 제시한다. 175,000줄 변경이 담긴 커밋을 반면교사로 들며, 이 습관이 미래의 유지보수자뿐 아니라 지금의 팀에도 도움이 된다고 말한다.

“it can be useful to outline some of the context and alternative approaches considered”

커밋 본문에 맥락과 검토한 대안까지 남기라는 지침은 별도 ADR 없이도 커밋 단위로 결정 기록을 시작할 수 있는 실용적 방법이다. 다음 사람이나 AI 에이전트가 blame과 로그로 "왜"를 찾을 수 있게 해 준다.

커밋 히스토리·변경 출처강제 장치·기여 정책결정 기록(ADR)

Mislav Marohnićmislav.net (personal blog)블로그영어

2014년 글로, 코드 한 줄의 의도는 그 코드를 만든 커밋과 PR 토론에 이미 기록돼 있다고 본다. git blame → git show → git log -S(pickaxe) → git log --merges --ancestry-path로 원래 PR을 찾아 이유를 되찾는 절차를 보여준다. "소프트웨어의 이야기는 최신 체크아웃만큼 중요하다"고 주장하며, 커밋 메시지가 "왜 이 변경이 필요한가, 어떻게 문제를 해결하는가, 어떤 부작용이 있는가"에 답해야 한다고 정리한다. blame 귀속을 지키려고 인접 줄을 건드리지 않는 줄 단위 코딩 스타일과 push 전 히스토리 정리(rebase)도 권한다.

“The story of a software matters as much as its latest checkout”

낯선 코드를 고치기 전에 "왜 이렇게 됐나"를 git만으로 되찾는 구체적인 명령 순서를 알려 준다. 별도 도구 없이 오늘 바로 쓸 수 있다.

커밋 히스토리·변경 출처

Chris Beamscbea.ms (personal blog)블로그영어

2014년 8월 31일 게시된 커밋 메시지 작성 가이드로, 제목과 본문 분리, 제목 50자 제한, 명령형 사용, 본문 72자 줄바꿈 등 일곱 가지 규칙을 제시한다. 일곱 번째 규칙은 본문에서 어떻게(how)가 아니라 무엇을(what)과 왜(why)를 설명하라는 것이다. diff는 무엇이 바뀌었는지만 보여 주고 왜 바뀌었는지는 커밋 메시지만이 제대로 말해 준다고 강조하며, 코드의 맥락을 다시 파악하는 비용을 줄이는 수단으로 커밋 메시지를 규정한다.

“A diff will tell you what changed, but only the commit message can properly tell you why.”

팀 커밋 규칙을 정할 때 변경의 \"왜\"를 본문에 남기도록 하는 짧고 실용적인 기준으로 바로 채택할 수 있어, 커밋 단위에서 의도 부채를 줄이는 출발점이 된다.

커밋 히스토리·변경 출처강제 장치·기여 정책

Scott Chacon, Ben Straubgit-scm.com (Pro Git)책영어

Pro Git 2판의 "검색" 장은 git grep과 함께, 문자열이나 함수의 변경 이력을 커밋 단위로 찾는 git log 검색 옵션을 설명한다. `-S`(pickaxe)는 지정 문자열의 출현 횟수를 바꾼 커밋만 보여주고, `-G`는 정규식으로 더 구체적으로 검색한다. `git log -L`은 함수나 줄 범위의 변경을 함수가 처음 만들어진 시점까지 패치 시퀀스로 보여준다.

“If you look at the diff of those commits, you can see that in ef49a7a the constant was introduced and in e01503b it was modified.”

이유를 모르는 코드를 수정하거나 지우기 전에 `-S`/`-L`로 그 코드를 도입한 커밋과 메시지를 찾으면, 별도 도구 없이 기존 git 이력만으로 코드의 의도를 되짚을 수 있다.

커밋 히스토리·변경 출처

Conventional Commits communityconventionalcommits.org표준·규약영어

커밋 메시지를 `<type>[optional scope]: <description>`, 선택적 본문, 선택적 푸터로 구조화하는 경량 규약이다. feat는 SemVer MINOR, fix는 PATCH, BREAKING CHANGE 푸터나 `!`는 MAJOR에 대응해 CHANGELOG 생성과 버전 결정을 자동화하는 것이 주목적이다. 본문은 코드 변경에 대한 "추가 맥락 정보"를 담는 선택(MAY) 항목일 뿐이고 동기나 근거 작성을 요구하지 않는다. 그래서 변경의 종류는 기계가 읽을 수 있지만 "왜"는 별도 규칙으로 채워야 한다.

“A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes.”

많은 팀이 이미 쓰는 커밋 규약이지만 타입 접두사만으로는 의도가 남지 않는다. 본문에 "왜"를 필수 항목으로 덧붙이는 팀 규칙의 출발점으로 삼을 만하다.

커밋 히스토리·변경 출처강제 장치·기여 정책

Aideraider.chat docs공식 문서영어

오픈소스 코딩 에이전트 aider의 git 연동 방식을 설명한 공식 문서다. aider는 git 저장소와 긴밀하게 연동되어 /undo로 AI 변경을 되돌리고 git 히스토리에서 aider가 만든 변경을 검토할 수 있게 한다. 기본값으로 aider가 작성한 커밋의 git author·committer 이름에 '(aider)'를 붙이고, 옵션으로 커밋 메시지 접두사 'aider: '나 Co-authored-by 트레일러로 표기 방식을 바꿀 수 있다. 이 표기는 AI가 관여했는지만 남기고, 어떤 대화나 의도에서 나온 변경인지는 담지 않는다.

“Aider marks commits that it either authored or committed. If aider authored the changes in a commit, they will have "(aider)" appended to the git author and git committer name metadata.”

커밋 author 이름이나 트레일러로는 AI가 관여했는지만 알 수 있고, 변경의 의도나 근거는 남지 않는다는 한계를 보여 준다. 그래서 세션이나 대화를 커밋에 연결하는 도구가 왜 필요한지 설명할 때 기준선 사례로 쓸 수 있다.

커밋 히스토리·변경 출처강제 장치·기여 정책

Git AI projectusegitai.com docs공식 문서영어

Git AI가 코딩 에이전트 훅으로 AI가 쓴 줄을 기록하는 방식을 설명하는 공식 문서다. 에이전트가 Edit·Write·Bash 도구를 호출할 때마다 훅이 `git ai checkpoint`를 실행하고, 직전 체크포인트와의 diff를 AI 작성 또는 사람 작성으로 표시해 두 편집을 가른다. 체크포인트는 커밋 전까지 `.git/ai`에 머물다가 커밋 때 파일별 세션·줄 범위와 세션 메타데이터를 담은 git note로 바뀌고, push/fetch로 원격에 동기화된다. 기록되는 것은 작성 출처와 전체 세션 링크이며, 결정의 이유 자체를 적는 기능은 아니다.

“After each `Edit`, `Write`, or `Bash` tool call, the hook runs `git ai checkpoint` to mark the lines just written as AI-authored.”

Claude Code·Cursor 같은 에이전트의 훅에서 줄 단위 AI 작성 출처와 세션 링크가 커밋 흐름에 자동으로 붙는 구조를 보여 준다. 나중에 코드를 편집하는 사람이나 에이전트가 해당 줄을 만든 세션 대화로 거슬러 올라가 맥락을 찾는 도구적 접근의 사례다.

커밋 히스토리·변경 출처

Linux kernel community (kernel.org)The Linux Kernel documentation공식 문서영어

리눅스 커널의 공식 패치 제출 가이드다. 'Describe your changes' 절은 먼저 문제와 사용자에게 드러나는 영향을 설명해 리뷰어에게 고칠 가치를 설득하고, 명령형으로 쓰며, 패치와 설명이 외부 자료 없이도 이해되도록 자기완결적으로 쓰라고 요구한다. 'The canonical patch format' 절은 설명 본문이 영구 changelog에 남으므로 당시 논의의 세부 사항을 잊은 지 오래된 유능한 독자도 이해할 수 있어야 한다고 명시한다. 대규모 협업 프로젝트가 커밋 본문을 의도를 기록하는 1차 매체로 제도화한 사례다.

“The explanation body will be committed to the permanent source changelog, so should make sense to a competent reader who has long since forgotten the immediate details of the discussion”

이슈 링크만 남기고 커밋 본문을 비우는 습관이 왜 위험한지 보여준다. 외부 링크는 사라질 수 있지만 changelog는 남는다. 가장 권위 있는 오픈소스 프로젝트 규칙 가운데 하나로, 커밋 기록을 의도 부채를 줄이는 수단으로 쓴 대표 사례다.

커밋 히스토리·변경 출처강제 장치·기여 정책결정 기록(ADR)

Addy Osmaniaddyosmani.com블로그영어

Addy Osmani가 2026년 5월 5일에 쓴 글이다. '어떻게'는 AI에 맡기되 '무엇'에 대한 판단은 유지하는 인지적 오프로딩과, 독립적인 견해 없이 AI 출력이 곧 자기 결론이 되는 인지적 항복(cognitive surrender)을 구분한다. Shaw와 Nave의 연구에서 AI가 틀린 시행의 73%에서 참가자가 틀린 답을 받아들였고 확신은 오히려 높아졌다는 결과와, AI로 코드를 생성하며 새 라이브러리를 배운 엔지니어의 이해도 점수가 17% 낮았다는 Anthropic 연구를 인용한다. 대응으로 출력을 보기 전에 기대치 세우기, AI가 쓰지 않은 것처럼 디프 읽기, 모델에 반론 요청하기, 검증을 종료 조건으로 삼기, 작은 PR, 혼자 코딩하는 시간 등을 제안한다.

“The AI's output becomes your output. There's nothing to override, because you never formed an independent view to compare it against.”

리뷰어가 AI의 확신을 그대로 물려받아 검토가 형식화되는 심리적 메커니즘과, 이를 깨는 개인·리뷰 습관을 정리한 글이다. 의도 부채가 사람 쪽에서 쌓이는 원인을 설명하는 근거로 쓸 수 있다.

이해 유지 실천개념 틀과 이론

Addy Osmani (Google Chrome)addyosmani.com (2026-03-14; O'Reilly Radar에 2026-04-13 재게재)블로그영어

2026년 3월 14일 게시된 에세이로, 이해 부채(comprehension debt)를 '시스템에 존재하는 코드의 양과 그중 어떤 인간이든 실제로 이해하는 양 사이에서 커지는 격차'로 정의한다. 기술 부채와 달리 이해 부채는 코드가 깨끗해 보이고 테스트가 통과하는 채로 쌓여 '거짓 자신감'을 낳으며, AI가 사람이 평가할 수 있는 속도보다 빨리 코드를 만들어 주니어가 시니어의 감사 속도보다 빠르게 코드를 생성하는 상황을 문제의 핵심 기제로 본다. Margaret-Anne Storey가 전한 학생 팀 사례(왜 그런 설계 결정을 했는지 아무도 설명하지 못해 무엇을 바꿔도 예상치 못한 곳이 깨지는 상황)와 Anthropic의 기술 형성 연구(arXiv 2601.20245)를 인용한다. 처방으로 변경의 목적을 작성 전에 명시하고, 검증을 사후 처리가 아닌 구조적 제약으로 두며, 시스템 수준 멘탈 모델을 유지하고, '테스트 통과'와 진짜 이해를 구분할 것을 제안한다.

“Comprehension debt is the growing gap between how much code exists in your system and how much of it any human being genuinely understands.”

의도 부채의 인접 개념인 이해 부채를 가장 널리 읽힌 형태로 정의한 글이며, '왜 그렇게 설계했는지 아무도 설명하지 못하는 팀' 사례가 의도 부채의 증상을 그대로 보여준다. 작성 전 목적 명시·검증의 구조화·시스템 멘탈 모델 유지 같은 실천은 팀에 문제를 설명하고 대응 규칙을 세울 때 출발점으로 쓸 수 있다.

이해 유지 실천개념 틀과 이론강제 장치·기여 정책

Dex Horthy (HumanLayer)AI Engineer YouTube 채널 (2026-07-23 공개 강연 영상)발표영어

HumanLayer의 Dex Horthy가 2025년 7월 아무도 코드를 읽지 않는 '불 꺼진(lights-off)' 에이전트 소프트웨어 공장을 운영했다가 실패한 경험을 다룬 강연이다. 프롬프트로 고칠 수 없는 문제가 생겨 사이트가 멈췄고, 그는 3개월 동안 읽지 않은 코드베이스를 직접 뒤져야 했다고 말한다. 원인은 기술이나 규모가 아니라 코딩 모델이 테스트 통과에만 보상받고 나쁜 아키텍처에는 벌점을 받지 않는 학습 방식이며, 하니스나 토큰을 늘려도 해결되지 않는다고 주장한다. 해법으로 사람이 계속 코드를 읽고 제품 검토·시스템 아키텍처·프로그램 설계·수직 슬라이스 순으로 선행 계획을 세우라고 권한다.

“Coding models are reinforced on one thing, did the test pass without breaking another, and nothing in that reward penalizes bad architecture, whose cost shows up months later.”

사람이 코드를 읽지 않고 에이전트에게 맡기면 설계 의도가 사라지고 코드베이스를 이해하지 못하게 된다는 실패 사례다. 사람의 코드 읽기와 설계 선행 계획으로 의도를 지켜야 한다는 근거가 된다.

이해 유지 실천강제 장치·기여 정책명세 주도 개발

Geoffrey Litt (Notion, design engineer)AI Engineer conference, July 2026 (written version on geoffreylitt.com)발표영어

노션의 디자인 엔지니어 Geoffrey Litt가 2026년 7월 AI Engineer 컨퍼런스에서 한 강연을 글로 옮긴 것이다. 에이전트가 자기 작업을 검증하는 능력이 좋아지면서 사람이 코드를 이해하는 목적은 '검증'에서 창작 과정에 '참여'하는 쪽으로 옮겨 간다고 주장한다. 개념을 충분히 알지 못하면 프로젝트에 참여하는 능력이 크게 제한된다고 본다. 이해를 돕는 도구로 /explain-diff 스킬(배경→직관→코드 순서의 '리터레이트 디프'), 5문항 퀴즈, 마이크로월드, 사람과 에이전트가 함께 쓰는 공유 공간을 제안한다.

“I won't send code to others until I can pass the quiz, and I do the same when reviewing others' code.”

에이전트가 만든 변경을 설명서·퀴즈·인터랙티브 도구로 이해하는 구체적인 워크플로를 보여 준다. 사람이 변경의 의도와 개념을 놓치지 않게 하는 실천 사례로 쓸 수 있다.

이해 유지 실천강제 장치·기여 정책

정도현 (ROBOCO Senior Consultant)ROBOCO 블로그블로그한국어

인지부채를 '쌓인 코드와 쌓인 이해 사이의 간극'으로 정의하고, 없애기보다 기술 부채처럼 제때 갚으며 관리하자고 제안한다. METR 2025 실험, GitClear의 대규모 커밋 분석, MIT Media Lab 연구를 근거로 든다. 관리법으로 개발자가 직접 답해야 하는 열린 질문인 '쪽지시험', 파일 순이 아니라 논리 개념 순으로 변경을 서술하는 Literate Code Diff, 불릿 대신 서사형 문서 세 가지를 제시한다.

“코드는 쌓이는데 이해는 쌓이지 않는다. 그 격차가 빚이다.”

AI가 쓴 코드의 설계 이유를 사람이 되찾는 구체적 루틴(쪽지시험, 개념 순 diff, 서사형 문서)을 한국어로 제안해 리뷰 절차에 바로 넣을 수 있다.

이해 유지 실천측정과 실증개념 틀과 이론

Kent BeckSoftware Design: Tidy First? (Substack 뉴스레터)블로그영어

Kent Beck이 2025년 6월 25일 자신의 뉴스레터에 쓴 글로, 약 4주간 에이전트와 함께 개발한 경험을 바탕으로 '바이브 코딩'과 '증강 코딩'을 구분한다. 바이브 코딩은 코드에 신경 쓰지 않고 시스템 동작만 보며 오류를 다시 '지니'에게 던지는 방식이고, 증강 코딩은 코드의 복잡도·테스트·커버리지를 여전히 중시하는 손코딩과 같은 가치 체계다. 그는 TDD를 유지하고 에이전트의 중간 결과를 더 주의 깊게 지켜보며 루프, 요청하지 않은 기능, 테스트 비활성화·삭제 같은 '속임수' 징후가 보이면 개입한다고 밝힌다. 사람이 코드에 대한 판단 기준을 놓지 않는 것이 핵심이라는 점에서 의도 부채 억제의 규율에 해당한다.

“In augmented coding you care about the code, its complexity, the tests, & their coverage. The value system in augmented coding is similar to hand coding--tidy code that works.”

'요청하지 않은 기능'을 합리적 다음 단계라도 드리프트 신호로 규정한 부분은 에이전트가 프로젝트 방향에서 벗어나는 순간을 리뷰에서 잡아내는 실용적 체크리스트가 된다.

이해 유지 실천강제 장치·기여 정책개념 틀과 이론

Thoughtworks Technology Advisory BoardThoughtworks Technology Radar (Hold 링; 2024년 10월 23일 최초 등재, 2025년 4월 갱신, 2025년 11월 5일 Vol 33 갱신)보고서영어

Thoughtworks Technology Radar가 2024년 10월 처음 Hold 링에 올리고 2025년 4월과 2025년 11월(Vol 33)에 갱신한 기법 블립이다. AI 코딩 도구가 프로토타이핑과 그린필드 프로젝트를 가속한다는 근거는 충분하지만 시간이 지나며 코드 품질이 떨어질 수 있다는 연구를 들어 '보류' 판정을 유지한다. GitClear 2024 연구의 중복 코드·코드 churn 증가와 리팩터링 감소, AI 기반 확신이 비판적 사고를 희생시킨다는 Microsoft의 지식 노동자 연구를 인용하고, 코딩 에이전트가 더 큰 변경 집합을 만들어 리뷰를 어렵게 한다고 본다. 대응으로 TDD와 정적 분석 같은 기존 관행을 팀의 curated shared instructions로 코딩 워크플로에 직접 내장하라고 권고한다.

“The rise of coding agents further amplifies these risks, since AI now generates larger change sets that are harder to review. As with any system, speeding up one part of the workflow increases pressure on the others.”

AI가 만든 코드를 사람이 검토·이해하지 않으면 품질이 저하되고 에이전트의 큰 변경 집합이 리뷰를 더 어렵게 한다는 점을 업계 레이더 수준에서 못 박은 근거다. 특히 TDD·정적 분석 규칙을 팀 공유 지침(instruction file)에 내장하라는 권고는 의도 부채 대응책 중 instruction-file 접근과 직접 연결되며, 명세로 의도를 남기더라도 사람의 이해가 따라오지 않으면 부채가 쌓인다는 SDD 논의의 균형추로 쓸 수 있다.

이해 유지 실천측정과 실증강제 장치·기여 정책저장소 지시 파일

Jason Gorman (Codemanship)Codemanship blog블로그영어

Codemanship의 Jason Gorman이 2025년 9월 30일에 쓴 글로, 팀이 이해하는 속도보다 빨리 코드를 만들 때 쌓이는 것을 '이해 부채(comprehension debt)'라고 부른다. 품질을 중시하는 팀은 LLM이 생성한 코드를 저장소에 넣기 전에 검토·이해·재작업하느라 속도가 느려지고, 그 후속 작업 때문에 번 시간이 상쇄되는 경우가 많다고 말한다. 반대로 이 과정을 건너뛰는 팀은 아무도 읽지 않은 코드를 체크인하게 된다고 경고한다. 정식 연구 인용 없이 저자의 관찰에 기반한 글이다.

“When teams produce code faster than they can understand it, it creates what I've been calling 'comprehension debt'.”

'이해 부채'라는 용어를 이름 붙인 초기 글이다. 생성 코드 검토를 생략하면 비용이 어디서 드러나는지 짧게 설명해 팀 공유용으로 적합하다.

이해 유지 실천개념 틀과 이론

Simon Willisonsimonwillison.net블로그영어

Simon Willison이 2025년 3월 19일에 쓴 글로, 바이브 코딩을 "LLM이 쓴 코드를 검토하지 않고 소프트웨어를 만드는 것"으로 정의하고 AI 보조 프로그래밍 전반과 구분한다. LLM이 코드를 썼더라도 사람이 검토·테스트하고 다른 사람에게 작동 방식을 설명할 수 있다면 바이브 코딩이 아니라 소프트웨어 개발이라고 본다. 저자는 다른 사람에게 정확히 무엇을 하는지 설명할 수 없는 코드는 저장소에 커밋하지 않는다는 규칙을 밝힌다. 바이브 코딩은 피해 가능성이 낮은 프로젝트에 한정하고 비밀 키, 사용량 과금, 외부 서비스 부하에 주의하라고 권한다.

“My golden rule for production-quality AI-assisted programming is that I won't commit any code to my repository if I couldn't explain exactly what it does to somebody else.”

커밋하는 사람이 코드를 설명할 수 있어야 한다는 원칙은 이해하지 못한 AI 코드가 쌓이는 것을 개인 단위에서 막는 규칙이며, 팀 리뷰 정책에 "설명할 수 없으면 커밋하지 않는다"는 규칙을 넣을 때 인용할 수 있는 원문이다.

이해 유지 실천강제 장치·기여 정책

Mitchell Hashimoto / Ghostty maintainersGitHub (ghostty-org/ghostty)공식 문서영어

터미널 에뮬레이터 Ghostty의 AI 사용 정책이다. 커밋 이력상 AI_POLICY.md는 2026-01-22에 추가됐다. 그보다 앞서 CONTRIBUTING.md에 AI 공개 의무가 2025-08-19에 들어갔고 2025-12에 강화됐다. 외부 기여자는 모든 AI 사용과 사용한 도구, AI 활용 범위를 공개해야 한다. 또 AI 없이 변경의 동작과 시스템 전체와의 상호작용을 설명하지 못하면 기여하지 말라는 '설명 가능성' 요건을 둔다. 저품질 AI 기여자는 공개 차단 목록에 올리며, 메인테이너는 이 규칙에서 예외다.

“The human-in-the-loop must fully understand all code. If you can't explain what your changes do and how they interact with the greater system without the aid of AI tools, do not contribute to this project.”

'AI 없이 이 변경이 시스템과 어떻게 맞물리는지 설명할 수 있는가'라는 한 문장 기준은 팀 리뷰 게이트로 옮기기 쉬운 의도 부채 방어선이다.

강제 장치·기여 정책이해 유지 실천

Python Software Foundation / CPython core team (Mariatta et al.)Python Developer's Guide공식 문서영어

CPython 기여자를 위한 AI 도구 사용 지침이다. 저장소 이력상 2024-10 Carol Willing이 추가한 짧은 생성형 AI 페이지에서 시작해 2026-05-21 Mariatta의 개편으로 현재 형태가 됐다. 제출자는 AI 사용 여부와 관계없이 내용 전체를 책임지고, AI가 한 작업을 자세히 검토해야 하며, 변경을 '자신의 말로' 설명할 수 있어야 한다. AI 사용 공개는 권장 사항일 뿐 의무가 아니며, 비생산적인 이슈나 PR을 반복하는 기여자는 차단될 수 있다.

“We expect PR authors and those filing issues to be able to explain their proposed changes in their own words.”

AI 사용 공개는 권장에 그치지만 변경을 설명할 책임은 의무로 둔 중간형 정책이다. 공개 의무 같은 절차 부담은 줄이면서, 제출자가 변경의 의도를 이해하고 있다는 점만은 확보하려는 팀이 참고할 수 있는 모델이다.

강제 장치·기여 정책이해 유지 실천

Dave Hansen / Linux kernel communitydocs.kernel.org (Documentation/process/generated-content.rst)공식 문서영어

Dave Hansen이 작성해 2026-01-20에 커밋된 리눅스 커널 문서로, 커밋에 Reviewed-by 12개가 달려 있다. AI 챗봇만이 아니라 checkpatch.pl --fix, Coccinelle 스크립트 같은 기존 도구까지 포함해 '도구가 만든 내용'을 다룬다. 기여자는 사용한 도구, 도구 입력, 프롬프트(긴 세션은 프롬프트 요약), 영향받은 부분, 테스트 방법을 커버 레터와 changelog에 밝혀야 한다. 또 제출한 모든 것을 이해하고 방어할 수 있어야 하며, 그렇지 못하면 제출하지 말라고 요구한다.

“If code was largely generated from a single or short set of prompts, include those prompts. For longer sessions, include a summary of the prompts and the nature of resulting assistance.”

도구로 만든 변경의 출처, 프롬프트, 영향 범위, 검증 방법을 changelog에 남기게 하므로, 나중에 '왜 이렇게 바뀌었나'를 역추적할 근거가 변경 기록에 쌓인다. AI 생성 PR 설명 템플릿의 체크리스트로 바로 옮겨 쓸 수 있다.

강제 장치·기여 정책커밋 히스토리·변경 출처이해 유지 실천

LLVM Project (drafted by Reid Kleckner)llvm.org documentation공식 문서영어

LLVM 프로젝트가 AI 도구를 써서 만든 기여에 적용하는 공식 정책이다. 이 정책을 추가한 PR #154441은 2025-08-19에 열렸고 2026-01-16에 병합됐다. 정책의 원칙은 '사람이 루프 안에 있어야 한다(human in the loop)'이다. 기여자는 LLM이 만든 코드와 텍스트를 직접 읽고 검토한 뒤에만 리뷰를 요청할 수 있고, 리뷰 중에 나오는 질문에 답할 수 있어야 한다. 또한 리뷰 비용이 프로젝트가 얻는 이득보다 큰 '추출적 기여(extractive contributions)'를 문제로 규정한다.

“Contributors must read and review all LLM-generated code or text before they ask other project members to review it.”

'리뷰에서 본인이 설명할 수 없는 AI 코드는 올리지 않는다'를 팀 PR 규칙으로 문서화할 때 참고할 수 있는 오픈소스 공식 정책 원문이다. 변경의 의도를 설명할 책임을 AI가 아니라 저자에게 둔다.

강제 장치·기여 정책이해 유지 실천

박공손 (우아한형제들 파트너셀프서비스팀)우아한형제들 기술블로그블로그한국어

사내 위키와 AI 에이전트용 규칙 문서(.claude/rules)에 적어 둔 아키텍처 규칙이 지켜지지 않았다. 리뷰에서 위반이 빠지고, 배포가 급하면 일단 머지하는 일이 반복되며, 신규 팀원은 무엇이 위반인지 모르고, 리뷰어는 같은 지적을 되풀이했다. 이를 해결하려고 규칙을 ArchUnit 테스트로 옮겨 CI에서 강제한 기록이다. 기존 위반은 FreezingArchRule로 동결해 신규 위반만 막았고, 규칙 문서를 ArchUnit 테스트로 바꾸는 작업과 레거시 위반을 분류하는 작업에 Claude 에이전트를 활용했다. 에이전트에 규칙을 주입해도 세션 컨텍스트에 따라 규칙을 어기는 경우가 있었다고 밝힌다.

“AI 에이전트를 이용해 규칙을 주입하더라도 세션별 컨텍스트에 따라 규칙을 위반하는 경우가 있었습니다.”

위키와 에이전트 규칙 파일에 적힌 규칙을 사람도 AI도 실제로는 어긴다는 점을 수치로 보여 주는 국내 사례다. 규칙을 문서에만 두지 않고 실행 가능한 검사로 고정하는 접근의 근거가 된다.

강제 장치·기여 정책저장소 지시 파일측정과 실증

Jason Brooks, Fedora Council, Fedora communityFedora Docs (Fedora Council Policies)공식 문서영어

Fedora Council의 AI 지원 기여 정책 1.0 버전으로, 마지막 검토일은 2025-10-24다. AI 도움을 허용하되, 기여자는 언제나 저자이며 품질·라이선스 준수·유용성을 보증하고 기여 전체에 책임을 진다고 규정한다. 기여의 상당 부분을 도구에서 수정 없이 가져왔다면 사용 사실을 공개해야 하고, git으로 관리되는 기여에는 Assisted-by: 커밋 트레일러를 권장한다. 정책은 이렇게 공개된 정보를 AI의 영향을 평가하고 모범 사례를 만들며 기존 프로세스를 조정하는 데 쓰겠다고 밝힌다.

“Information about the use of AI tools will help us evaluate their impact, build new best practices and adjust existing processes.”

Assisted-by 커밋 트레일러로 AI 사용 사실을 이력에 남기게 하고, 이 정보를 AI 영향 평가와 프로세스 조정에 쓰겠다고 명시한 오픈소스 정책 사례다. 설계 의도 자체를 기록하는 장치는 아니지만, 커밋 이력에 AI의 출처 정보를 남겨 나중에 추적할 수 있게 하는 조직 차원의 규칙으로 참고할 수 있다.

강제 장치·기여 정책커밋 히스토리·변경 출처

QEMU Projectqemu.org developer documentation공식 문서영어

QEMU 개발자 문서의 코드 출처(Code provenance) 페이지는 AI 생성 콘텐츠를 포함하거나 거기서 파생됐다고 판단되는 기여를 거절한다는 프로젝트 정책을 명시한다. 근거는 기여자가 DCO(Developer's Certificate of Origin)를 지키려면 기여 내용의 저작권과 라이선스 상태를 완전히 이해해야 하는데, AI 출력은 그 상태가 법적으로 정립되지 않았다는 점이다. 예외는 qemu-devel 메일링 리스트에서 제안할 수 있지만, 예외가 인정돼도 Signed-off-by 요건에 따라 작성자가 패치 전체를 책임져야 한다.

“To satisfy the DCO, the patch contributor has to fully understand the copyright and license status of content they are contributing to QEMU.”

기여자가 내용의 출처와 상태를 이해하고 증명할 수 없으면 받지 않는다는 원칙은, 근거를 인용할 수 없는 변경을 막는 리뷰 정책의 가장 보수적인 참조점이다.

강제 장치·기여 정책

Dex Horthy (HumanLayer)AI Engineer Code 2025 (AI Engineer Code Summit, New York, 2025-11)발표영어

기존 코드베이스에서 코딩 에이전트가 재작업과 코드 churn을 늘린다는 문제를 '컨텍스트 엔지니어링'으로 다루는 20분 31초 강연이다. 컨텍스트 윈도우가 채워질수록 결과가 나빠지는 '멍청한 구간(dumb zone)'을 피하기 위해, 탐색 결과를 리뷰 가능한 산출물로 압축해 새 컨텍스트에서 이어가는 '의도적 압축(intentional compaction)'과 조사→계획→구현을 분리하는 워크플로를 제안한다. 큰 diff 대신 조사·계획 단계에서 사람이 검토해 오해를 일찍 잡고, 시스템이 어떻게 왜 바뀌는지에 대한 팀의 공유 이해인 '정신적 정렬(mental alignment)'을 지키는 것이 핵심이다.

“This review stage protects mental alignment: a shared understanding of how the system is changing and why.”

조사·계획 문서를 사람이 먼저 읽고 승인하는 절차는 에이전트의 방향 이탈을 코드 리뷰 이전에 잡는 구체적인 방법이며, 강연이 말하는 '정신적 정렬'은 시스템이 왜 바뀌는지에 대한 공유 이해를 유지하는 것이라 의도 부채 문제와 직접 맞닿는다.

강제 장치·기여 정책결정 기록(ADR)이해 유지 실천조직 지식 검색

Jonathan CorbetLWN.net기사영어

2025년 12월 11일 LWN 기사로, 리눅스 커널 메인테이너들이 머신러닝 도구 사용 정책을 논의한 내용을 전한다. 참석자들은 LLM을 썼더라도 패치의 책임은 사람에게 있고, 사람이 관여하지 않은 순수 기계 생성 패치는 받지 않는다는 데 뜻을 모았다. Assisted-by 태그는 강제하지 않는 문서 권고로 두고 자연스럽게 발전하도록 하기로 했다. 도구 접근성 불평등, 상용 도구 의존, 리뷰 인력 부족 같은 우려도 함께 논의됐다.

“Human accountability for patches is critical, and that use of a large language model in the creation of a patch does not change that. Purely machine-generated patches, without human involvement, are not welcome.”

대형 오픈소스 공동체가 AI 도구에 대응할 때 먼저 사람의 책임 원칙에 합의하고 출처 표시 태그는 강제하지 않는 권고로 두는 순서를 택했다. 팀에 AI 사용 규범을 처음 들일 때 참고할 수 있는 절차 사례다.

강제 장치·기여 정책

Alvin Sng (Factory.ai)Factory.ai News, 2025-09-05블로그영어

글로 쓴 가이드라인에 기대지 말고 팀 관례를 린트 규칙으로 코드화해 에이전트가 코드를 생성하는 중에 규칙에 부딪히게 하라고 주장하며, 린트를 사람의 의도와 에이전트 산출물을 잇는 '실행 가능한 명세'로 규정한다. 규칙 범주로 grep 가능성, glob 가능성, 아키텍처 경계, 보안·프라이버시, 테스트 용이성과 커버리지, 관측성, 문서 신호의 일곱 가지를 제시한다. TypeScript 예로 default export 금지, 절대 경로 import(@app/feature/...), enums.ts·types.ts·index.ts 같은 결정론적 파일 배치를 든다.

“Agents write the code; linters write the law.”

팀의 의도를 문서가 아니라 강제 가능한 린트 규칙으로 옮겨 에이전트 변경이 방향에서 벗어나는 것을 막는 구체적 실무 지침이다. TypeScript 코드베이스의 예시 규칙 목록을 제공한다.

강제 장치·기여 정책결정 기록(ADR)

Gentoo CouncilGentoo Wiki공식 문서영어

Gentoo Council이 2024-04-14에 채택한 정책으로, 자연어 처리 AI 도구의 도움을 받아 만든 콘텐츠를 Gentoo에 기여하는 것을 명시적으로 금지한다. 근거는 저작권, 품질, 윤리 세 가지다. 품질 근거에서는 LLM이 그럴듯하지만 의미 없는 내용을 만들어 내 프로젝트 품질을 떨어뜨리고 개발자와 사용자에게 과도한 리뷰 부담을 준다고 적는다. AI 관련 소프트웨어를 패키징하거나 업스트림이 AI 도구로 개발한 소프트웨어를 다루는 것은 금지하지 않는다.

“It is expressly forbidden to contribute to Gentoo any content that has been created with the assistance of Natural Language Processing artificial intelligence tools.”

허용·공개형 정책과 대비되는 전면 금지형 정책의 원문이다. 팀이 AI 기여 규칙의 강도를 정할 때 스펙트럼의 한쪽 끝으로 참조할 수 있다. 리뷰 부담을 금지 근거로 든다는 점에서 이해 부채 논의와도 이어진다.

강제 장치·기여 정책

Lukas NiessenGitHub (MIT)도구영어

Java의 ArchUnit에 해당하는 TypeScript·JavaScript용 아키텍처 테스트 라이브러리로, 레이어 의존, 순환 의존, 명명 규칙, LCOM 등 코드 지표, 슬라이스·UML 검증, Nx 모노레포 경계를 테스트 코드로 검사한다. Jest·Vitest·Jasmine용 비동기 matcher(toPassAsync())를 제공하고, 패턴에 맞는 파일이 없으면 기본적으로 테스트를 실패시켜 오타 때문에 테스트가 그냥 통과하는 일을 막는다. README에는 LLM 기반 아키텍처 테스트 라이브러리('퍼지' fitness function) 개발 계획이 적혀 있다.

“ArchUnitTS detects this, we call it an empty test, and your test fails. This is the default behavior, you can customize it to allow empty tests if you want to.”

아키텍처 결정을 CI에서 도는 실행 가능한 테스트로 옮겨, 의도를 모르는 사람이나 AI 에이전트가 코드를 고쳐도 레이어·의존 규칙을 어기면 빌드에서 걸리게 한다. Java ArchUnit 사례를 TypeScript 프런트엔드 저장소에 적용할 때 가장 가까운 도구다.

강제 장치·기여 정책

Tom Manshreck (저), Riona MacNamara (편), GoogleO'Reilly 『Software Engineering at Google』 (abseil.io 무료 HTML판)책영어

구글이 문서를 코드처럼 다루게 된 경위와 g3doc(코드 안에 Markdown 문서를 두는 내부 프레임워크)을 설명한 장이다. 사내 위키 GooWiki를 폐기할 때 문서의 약 90%가 최근 몇 달간 조회나 갱신이 없었다고 밝히며, 문서를 소스 관리에 넣고 소유자를 정하고 리뷰와 버그 추적, 주기적 신선도 평가를 거치게 했다고 설명한다. 참조·설계 문서·튜토리얼·개념 문서·랜딩 페이지 다섯 유형을 구분하고, 도입부에서 WHO/WHAT/WHEN/WHERE/WHY를 HOW보다 먼저 답하라고 권한다. 설계 문서는 결정 근거와 트레이드오프를 담는 협업 문서로 주로 Google Docs에서 공유되며, 대부분 팀은 큰 프로젝트 착수 전에 승인된 설계 문서를 요구한다고 적는다.

“When we deprecated GooWiki, we found that around 90% of the documents had no views or updates in the previous few months.”

위키 문서가 방치되는 현상(90% 미조회)과 문서를 소스 관리·소유자·리뷰 체계에 넣어 품질을 회복한 구글의 경험을 보여 주어, 팀 지식을 저장소 가까이 두고 코드처럼 관리할 근거가 된다.

강제 장치·기여 정책결정 기록(ADR)개념 틀과 이론

Tom Preston-Werner (GitHub 공동창업자)개인 블로그 tom.preston-werner.com블로그영어

코드·테스트·명세보다 먼저 README를 쓰라고 제안한 에세이다. 잘못된 명세를 완벽하게 구현한 코드도, 문서 없는 훌륭한 라이브러리도 사실상 가치가 없다고 본다. README 하나를 프로젝트의 설계 산출물이자 소개 문서로 삼으면 워터폴식 과잉 명세와 무문서라는 양극단을 모두 피할 수 있다고 주장한다. 의도 부채 관점에서는 구현보다 의도를 먼저 기록하는 가장 가벼운 절차로 읽을 수 있다.

“A perfect implementation of the wrong specification is worthless.”

다음 편집자(사람이든 에이전트든)가 가장 먼저 여는 README 한 파일에 무엇을 왜 만드는지를 코드보다 먼저 적는 습관은 의도 부채를 원천에서 줄이는 최소 비용 실천의 초기 사례다.

강제 장치·기여 정책명세 주도 개발

Linux kernel communityThe Linux Kernel documentation공식 문서영어

리눅스 커널이 AI 도구로 기여할 때의 방식을 정한 공식 프로세스 문서다. AI 에이전트는 Signed-off-by 태그를 달 수 없고, 사람 제출자가 모든 AI 생성 코드를 검토하고 기여 전체에 책임을 지도록 정한다. 기여에는 사용한 LLM과 특수 분석 도구를 적은 Assisted-by 트레일러를 붙이게 한다. 대형 오픈소스가 세션 원문 대신 커밋 트레일러라는 최소한의 출처 표기와 사람의 책임을 규범으로 정한 사례다.

“When AI tools contribute to kernel development, proper attribution helps track the evolving role of AI in the development process.”

별도 도구 없이 커밋 트레일러와 책임 규칙만으로 AI 기여의 출처를 남기는 최소 기준이다. 팀 커밋 컨벤션을 정할 때 그대로 참고할 수 있다.

강제 장치·기여 정책커밋 히스토리·변경 출처

curl projectcurl.se공식 문서영어

curl 기여 가이드의 'On AI use in curl' 절이다. AI 도구로 curl의 문제를 찾았다면 리포트에 그 사실을 반드시 밝혀야 하고, 결과가 실제로 맞는지 직접 확인한 뒤 본인이 이해한 대로 리포트를 쓰라고 요구한다. 조작된 가짜 리포트를 낸 사용자는 즉시 차단한다. AI의 도움을 받은 PR도 코딩 표준·문서화·테스트 등 기존 요구사항을 모두 충족해야 한다.

“If you actually find a problem with an AI and you have verified it yourself to be true: write the report yourself and explain the problem as you have learned it.”

AI가 만든 분석이나 코드를 프로젝트에 넣을 때 '직접 검증하고 본인이 이해한 말로 설명한다'는 책임을 제출자에게 두는 오픈소스 규범의 사례다. AI 산출물 때문에 이해가 흐려지는 것을 기여 정책으로 막는 방식에 해당한다.

강제 장치·기여 정책이해 유지 실천

Daniele Procidadiataxis.fr (공식 사이트)공식 문서영어

Diátaxis는 문서를 사용자의 필요에 따라 tutorials, how-to guides, technical reference, explanation 네 유형으로 나누어 체계적으로 작성하는 방법론이다. 사이트는 이 원칙이 유지보수자가 자기 문서를 점검하게 하는 '품질의 능동 원칙'을 준다고 밝힌다. 그중 explanation은 설계 결정, 역사적 이유, 기술적 제약 등 '왜 이렇게 되었는가'를 설명하고 대안까지 다루는 이해 중심 문서로 규정된다.

“Diátaxis is a widely-adopted, pragmatic and systematic approach to thinking about and creating documentation.”

결정의 이유, 역사, 제약, 버린 대안을 절차·참조 문서와 분리해 'explanation'이라는 독립 유형으로 기록하는 분류 기준을 제공한다. 이 기준은 의도를 문서로 남기는 틀로 참고할 수 있다.

강제 장치·기여 정책개념 틀과 이론

Eric Holscher 및 Write the Docs 커뮤니티Write the Docs 가이드공식 문서영어

문서를 코드와 같은 도구로 써야 한다는 Docs as Code 철학을 정의한 Write the Docs 커뮤니티 가이드다. 도구와 실천으로 이슈 트래커, 버전 관리(Git), 플레인 텍스트 마크업(Markdown, reStructuredText, Asciidoc), 코드 리뷰, 자동 테스트를 든다. 이점으로는 작성자와 개발팀의 통합, 개발자가 문서 초안을 쓰는 경우가 많아지는 점, 문서 요건으로 기능 머지를 막아 작업 기억이 생생할 때 문서를 쓰게 하는 점을 제시한다.

“Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code”

문서를 코드와 같은 저장소와 리뷰 흐름에 두면, 코딩 에이전트도 코드와 같은 경로로 의도 기록을 읽을 수 있다는 점을 시사한다. '문서 없는 기능은 머지하지 않는다'는 게이트를 에이전트 작업에도 적용하면, 의도 기록이 코드 변경과 함께 리뷰를 통과하게 만드는 최소 규칙이 된다. 에이전트 적용은 이 프로젝트의 해석이고 원문에 있는 내용은 아니다.

강제 장치·기여 정책

The NetBSD Foundation (core team)netbsd.org developer documentation공식 문서영어

NetBSD 커밋 가이드라인은 '오염된 코드(tainted code)를 저장소에 커밋하지 말라'는 항목 아래에서 LLM이나 유사 기술로 생성한 코드를 오염된 코드로 추정한다. 이런 코드는 core 팀의 사전 서면 승인 없이는 커밋할 수 없다. 예시 도구로 Copilot, ChatGPT, Code Llama를 든다. 페이지에는 조항의 채택일이나 개정일이 적혀 있지 않다.

“Code generated by a large language model or similar technology, such as GitHub/Microsoft's Copilot, OpenAI's ChatGPT, or Facebook/Meta's Code Llama, is presumed to be tainted code”

오픈소스 프로젝트가 AI 생성 코드의 반입을 '기본 금지, 중앙 승인 시 예외'로 통제하는 정책 사례다. 조항은 코드의 출처와 오염 여부를 문제로 삼을 뿐 설계 의도 보존을 다루지 않으므로, 의도 부채의 직접 해법이 아니라 AI 기여 정책의 비교 사례로만 인용해야 한다.

강제 장치·기여 정책

LinearBLinearB Resources보고서영어

LinearB가 42개국 4,800개 이상 조직의 PR 810만 건 이상을 분석한 2026년 벤치마크 보고서다. AI가 만든 PR은 리뷰 착수까지 4.6배 오래 기다리고, 에이전트형 AI PR의 PR Pickup Time은 AI 도움 없이 작성한 PR보다 5.3배 길다. 다만 일단 리뷰가 시작되면 2배 빠르게 처리된다. AI 생성 PR의 수락률은 32.7%로 수동 PR의 84.4%보다 크게 낮으며, 봇 PR 수락률은 도구별로 달라 Devin은 상승하고 Copilot은 하락하는 추세를 보였다.

“Acceptance Rates for AI-generated PRs are significantly lower than manual PRs (32.7% vs. 84.4%).”

AI 생성 PR의 수락률(32.7%)이 사람 PR(84.4%)보다 크게 낮다는 대규모 수치는 AI가 만든 변경이 리뷰 단계에서 자주 받아들여지지 않는다는 산업계 근거다. 거부 원인은 보고서가 밝히지 않으므로, 의도 부채와의 연결은 해석으로 제시해야 한다.

측정과 실증

Shyam Agarwal, Courtney Miller, Christian Kästner, Bogdan Vasilescu — Carnegie Mellon UniversityarXiv preprint (2607.07980), submitted 2026-07-08논문영어

코딩 에이전트가 PR 전체를 작성하는 시대의 코드 리뷰를 다룬 2026년 7월 논문으로, 엔지니어링 블로그와 Reddit 스레드 38,709건 중 층화 무작위 표본 3,100건을 LLM 보조 파이프라인으로 코딩해 26개 구성개념과 67개 관계(64개 방향성, 3개 논쟁 중)로 이뤄진 인과 이론을 세웠다. 공개 GitHub 관찰에서는 에이전트 작성 PR이 사람 PR보다 리뷰 논의가 절대량과 변경 줄당 모두 적고 수 배 빨리 병합됐으며, 에이전트 PR의 40.1%는 에이전트를 호출한 개발자 본인만 검토한 반면 사람 PR은 21.5%였다(다만 분석 선택에 따라 결과 방향이 뒤집힐 수 있음을 밝힌다). 이론은 '리뷰가 코딩 에이전트의 소프트웨어 영향이 결정되는 통제 지점'이며, 얕은 리뷰와 불투명성이 이해 부채(comprehension debt)를 늘려 리뷰 기술·유지보수성·집단 소유권·지식 이전을 잠식한다고 정리한다.

“Third, the act of low-depth reviews creates comprehension debt, undermining the developers' future review skills for the code base.”

에이전트 PR의 40.1%가 호출한 사람만 보고 병합된다는 관찰과 함께 리뷰를 '의도가 지켜지는 통제 지점'으로 이론화하고, 얕은 리뷰가 이해 부채를 쌓아 지식 이전을 잠식한다고 명시하므로, 팀의 리뷰 정책을 의도 부채 관점에서 다시 설계할 때 근거가 된다.

측정과 실증이해 유지 실천개념 틀과 이론강제 장치·기여 정책

Bill Doerrfeld — LeadDev (reporting GitClear's 'The AI Code Quality Maintainability Gap' research by Bill Harding, GitClear CEO)LeadDev기사영어

GitClear의 2026년 보고서 'The AI Code Quality Maintainability Gap'을 다룬 2026년 7월 7일자 LeadDev 기사로, 2023~2026년 6억 2,300만 건의 실제 코드 변경을 분석한 결과를 정리한다. 코드 중복은 81% 증가, 코드 이동(재사용) 지표는 70% 감소, 레거시 리팩터링은 2023년 대비 74% 감소, 기능 간 연결성은 35% 감소, 오류 마스킹은 47% 증가했다고 전한다. GitClear CEO Bill Harding은 AI가 요청마다 새 패키지를 만들어 같은 기능의 구현이 다섯 개씩 생기고, 유지보수자가 어느 오류 처리가 이유가 있어 추가됐고 어느 것이 AI 편의로 추가됐는지 가려내야 하는 부채가 남는다고 말한다. GitClear 원문 페이지는 접근이 차단되어(HTTP 403) 이 기사를 근거로 삼는다.

“That shortcut becomes tech debt for the maintainers, who eventually need to ascertain which error handling was added for cause, versus those added for AI expediency.”

오래된 코드를 손보는 변경이 74% 줄고, 유지보수자가 어떤 오류 처리가 '이유가 있어' 들어갔는지 사후에 가려내야 한다는 Harding의 지적은 의도 부채의 실측 사례다. 레거시의 '왜'를 아는 사람이 줄어드는 만큼 오래된 모듈에 결정 기록을 남겨야 하는 이유를 수치로 뒷받침한다.

측정과 실증

Muhammad Ovais AhmadarXiv 2604.13277; Proceedings of EASE 2026 Companion논문영어

Muhammad Ovais Ahmad가 2026년 4월 14일 arXiv에 올린 논문으로, EASE 2026 Companion 논문집에 실린다고 표기돼 있다. 논문은 이해 부채를 개발 팀이 코드베이스에 대해 아는 것과 유지·수정에 실제로 필요한 이해 사이에서 커지는 격차로 정의한다. 또 이 부채는 코드가 아니라 팀의 집단 인지에 존재한다는 점에서 기술 부채와 다르다고 주장한다. 학부 소프트웨어 공학 프로젝트에서 학생 207명이 8주 동안 쓴 성찰 일지 621건을 질적으로 분석해, 이해 부채가 쌓이는 네 가지 패턴과 이를 줄이는 한 가지 패턴을 찾았다. 완화책으로는 검증 관행, 구조화된 회고, 능동 학습 평가를 강조하는 교육 전략을 제안한다.

“We argue that CD is distinct from traditional technical debt because it resides in the collective cognition of development teams rather than in the codebase itself.”

이해 부채가 코드가 아니라 팀의 인지에 쌓인다는 관점은 의도 부채와 맞닿아 있다. 논문이 찾은 네 가지 누적 패턴은 팀 회고에서 우리 팀이 어느 패턴에 해당하는지 점검하는 기준으로 쓸 수 있다.

측정과 실증이해 유지 실천강제 장치·기여 정책

Aadit Shah (Mintlify)Mintlify 블로그보고서영어

문서를 코딩 에이전트에 제공하는 네 가지 형식(HTML, 순수 Markdown, llms.txt 링크를 포함한 Markdown, llms.txt를 인라인한 Markdown)을 비교한 벤치마크다. Mintlify 문서 사이트 20곳에서 사이트당 5개 질문을 형식마다 3회씩, 모두 2,400회 실행했다. 작업당 404 오류는 HTML 2.23회, Markdown 1.42회, llms.txt 링크를 포함하면 0.11회였고, 정답률은 모든 형식에서 90%대 중후반으로 비슷했다. 결론은 형식보다 에이전트에게 '지도'를 링크로 주는 것이 헛탐색과 비용을 줄인다는 것이다.

“the map didn't make them more right, it just got them there faster and cheaper”

에이전트에게 문서 전체를 넣기보다 인덱스(지도)를 링크로 주는 편이 헛탐색과 비용을 줄인다는 정량 근거다. 프로젝트 지식 SSOT에 에이전트용 인덱스 파일을 두는 설계를 뒷받침한다.

측정과 실증조직 지식 검색

DXDX (State of AI Impact in Engineering, quarterly)보고서영어

2026년 7월 22일 발표된 DX의 분기 보고서로, 500개 이상 엔지니어링 조직의 시스템 텔레메트리와 설문 데이터를 결합해 2026년 4–6월을 분석했다. 전체 코드의 52.7%가 AI 생성으로 두 분기 전 24%에서 크게 늘었고, 헤비 유저는 주 6시간 이상을 절약하며 엔지니어당 주간 PR(TrueThroughput 중간값)은 4분기 동안 1.42건에서 1.94건으로 37% 늘었다. 반면 개발자 경험 지수(DXI)는 67에서 65로 내려가고, 변경이 무언가를 망가뜨리지 않으리라는 확신(change confidence)은 6.1% 하락했다. 코드 유지보수성은 AI가 코드베이스 탐색과 이해를 도와 3.8% 개선됐다고 보고한다.

“Change confidence, developers' trust that their changes won't break something, fell 6.1%.”

AI 생성 코드 비중과 처리량은 늘었지만, 개발자가 자기 변경을 신뢰하는 정도(변경 확신도)는 떨어졌다는 분기 데이터다. 코드 이해는 쉬워졌어도 변경의 안전성을 확신하기는 어려워진 상황을 보여 주며, 의도 부채의 증상으로 읽을 수 있는 정량 근거다(해석은 이 페이지의 것이다).

측정과 실증

Nicholas Gardella, James Prather, Juho Leinonen, Paul Denny, Raymond Pettit, Sara L. RiggsarXiv 2604.18538 (cs.HC)논문영어

Gardella, Prather, Leinonen, Denny, Pettit, Riggs가 2026년 4월 20일 arXiv에 올린 통제 실험이다. 초보자 22명이 시간 압박 아래 사람과 2인 1조로 한 번, GitHub Copilot과 혼자서 한 번, 각 20분씩 Python 과제를 풀었고 일주일 뒤 혼자서 재시험을 봤다. Copilot 조건의 즉시 성과가 사람 짝보다 유의하게 높았고 작업 부하의 일부 차원도 줄었다. 그러나 사람과의 협업이 더 긍정적이고 각성도 높은 감정을 낳았고, 일주일 뒤 재시험에서는 AI 조건의 성과 하락 폭이 더 컸다(절대 하락 자체는 비유의).

“a nonsignificant absolute retest performance reduction in the AI condition and a larger retest performance decrement in the AI condition”

AI 보조가 당장의 성과와 작업 부하를 개선해도 일주일 뒤 수행은 더 크게 떨어진다는 초보자 대상 실험 근거다. AI와 작업할 때 이해가 사람에게 남지 않는 인지·이해 부채 측면을 보여 주므로, 사람 사이의 협업과 지식 공유를 유지해야 한다는 논의의 참고 자료가 된다.

측정과 실증이해 유지 실천

Judy Hanwen Shen, Alex Tamkin (Anthropic)Anthropic Research보고서영어

Anthropic의 Judy Hanwen Shen과 Alex Tamkin이 2026년 1월 29일 발표한 무작위 대조 실험이다. 대부분 주니어인 소프트웨어 엔지니어 52명이 낯선 Python 라이브러리(Trio)로 과제를 수행한 뒤 퀴즈를 봤는데, AI 사용 그룹은 평균 50%, 직접 코딩 그룹은 67%로 17%포인트 낮았다(Cohen's d=0.738, p=0.01). AI 그룹은 약 2분 빨리 끝냈지만 이 차이는 유의하지 않았고, 점수 격차는 디버깅 문항에서 가장 컸다. 저자들은 AI를 코드 생성뿐 아니라 후속 질문·설명 요청으로 이해를 쌓는 데 쓰는 사용 방식이 숙련 형성에 유리하다고 본다.

“Cognitive effort—and even getting painfully stuck—is likely important for fostering mastery.”

AI 도움으로 코드를 만들어도 그 코드에 대한 이해가 저절로 생기지 않는다는 점, 즉 의도 부채의 개인 차원을 수치로 보여 준다. 팀에 리뷰 정책이나 설명 요청 관행을 도입하자고 설득할 때 근거로 쓸 수 있다.

측정과 실증이해 유지 실천

Judy Hanwen Shen (Anthropic Fellows Program), Alex Tamkin (Anthropic)arXiv preprint (arXiv:2601.20245, cs.CY; v1 2026-01-28, v2 2026-02-01)논문영어

개발자 52명(처치·통제 각 26명)을 무작위 배정해 익숙하지 않은 파이썬 비동기 라이브러리 Trio 과제를 AI 보조 유무로 수행하게 한 뒤, 개념 이해·코드 읽기·디버깅을 묻는 27점 만점 퀴즈로 학습 결과를 측정한 사전등록(OSF) 실험이다. AI 집단은 평균 4.15점(17%, 논문 표현으로 2등급) 낮았고(Cohen's d=0.738, p=0.010) 완료 시간의 통계적으로 유의한 단축은 없었으며, 격차는 디버깅 문항에서 가장 컸다. 화면 녹화를 분석해 여섯 가지 AI 상호작용 패턴을 분류한 결과, 코드 생성을 전부 위임하거나 반복 디버깅을 맡긴 저점수 패턴(퀴즈 평균 24~39%)과 개념 질문·설명 요청으로 인지적 관여를 유지한 고점수 패턴(65~86%)이 갈렸다. 전부 위임한 참가자(n=4)는 약 19.5분으로 통제군 평균 23분보다 빨랐지만 학습 결과는 가장 낮았고, 저자들은 AI가 높인 생산성이 역량의 지름길은 아니라고 결론짓는다.

“AI use impairs conceptual understanding, code reading, and debugging abilities, without delivering significant efficiency gains on average.”

코드를 얻는 것과 코드를 이해하는 것이 개인 수준에서 분리되는 메커니즘을 실험으로 보여주며, 전부 위임 대신 개념 질문과 설명 요청을 섞으면 속도를 크게 잃지 않고도 이해를 지킬 수 있음을 시사한다. AI 사용 습관을 바꾸는 개인 지침으로 쓸 수 있는 의도 부채·이해 부채의 실증 근거다.

측정과 실증이해 유지 실천

Ningzhi Tang, Chaoran Chen, Gelei Xu, Yiyu Shi, Yu Huang, Collin McMillan, Tao Dong, Toby Jia-Jun LiarXiv cs.SE/cs.AI/cs.HC (2026-05-28 v1, 2026-08-31 v2)논문영어

벤치마크 궤적이 아니라 실제 개발 세션 로그를 관찰해 코딩 에이전트가 개발자 기대와 어긋나는 방식을 분류한 대규모 연구다. SpecStory 내보내기(2024년 9월~2026년 4월)와 Entire.io 로그로 모은 1,639개 저장소의 IDE·CLI 세션 20,574개를 분석해, 개발자의 되돌림(pushback)으로 드러난 오정렬을 형태·원인·비용·해결의 네 차원으로 코딩했다. 프로젝트 오진단, 개발자 의도 오독, 명시적 제약 위반, 자의적 범위 확장, 잘못된 구현, 실행 오류, 부정확한 자기 보고의 일곱 가지 반복 패턴을 도출했으며, 제약 위반과 의도 오독이 가장 흔하고 가시적 해결의 대부분이 개발자의 명시적 정정에 의존한다는 결과는 프로젝트의 제약과 의도가 에이전트에 전달되지 않을 때 생기는 비용을 현장 데이터로 보여준다.

“90.50% of episodes impose effort and trust costs rather than irreversible system damage, 91.49% of visible resolutions still require explicit user correction”

에이전트가 명시된 규칙을 어기고 의도를 오독하는 일이 얼마나 흔하며 그 뒷수습을 누가 하는지 실제 세션 데이터로 수치화해, 프로젝트의 제약과 의도를 에이전트가 읽을 수 있는 형태로 미리 외재화해야 하는 이유를 설득하는 근거로 쓸 수 있다.

측정과 실증

Sonar (Anirban Chatterjee)Sonar Blog (State of Code Developer Survey)보고서영어

2026년 1월 8일 발표된 Sonar의 전문 개발자 설문(1,100명 이상) 보고서다. 개발자들은 커밋하는 코드의 42%가 이미 AI 생성·보조 코드이며 2027년에는 65%에 이를 것으로 예상했다. AI 코딩 도구를 써본 개발자의 72%가 매일 쓰지만, 96%는 AI 생성 코드를 완전히 신뢰하지 않고 커밋 전에 항상 검증하는 비율은 48%에 그친다. 38%는 AI 코드 리뷰가 동료가 쓴 코드 리뷰보다 더 많은 노력이 든다고 답했으며, 보고서는 검증을 핵심 차별 요소로 제시한다.

“But 96% of developers do not fully trust AI-generated code, and only 48% always verify it before committing.”

커밋 코드의 절반 가까이가 AI 생성·보조 코드이고 항상 검증하는 개발자는 절반에 못 미친다는 수치는, 작성 의도를 설명할 사람이 없는 코드가 빠르게 쌓이는 배경을 보여준다.

측정과 실증이해 유지 실천

Faros AI (Faros Research)Faros AI (AI Engineering Report 2026)보고서영어

2026년 4월 12일 공개된 Faros AI의 2026년판 보고서 요약으로, 4,000개 이상 팀 2만 2,000명 개발자의 2년치 텔레메트리를 근거로 한다. AI 도구 주간 활성 사용자 50%를 넘는 팀이 80%에 이르고 수락률이 20%에서 60%로 올랐으며 처리량도 늘었지만, 코드 churn(분기 내 병합 코드의 삭제 대비 추가 줄 비율)이 861% 증가하고 PR당 인시던트 비율이 242.7%, 개발자당 버그가 54% 늘었다. 작업 재시작이 13.8%, 7일 이상 활동 없는 진행 중 과제가 26% 증가했고, 중간값 리뷰 시간은 441.5% 늘었으며 리뷰 없이 병합된 PR은 31.3% 증가했다. 성숙한 DevOps를 갖춘 고성과 조직도 같은 하류 악화를 겪는다고 보고한다.

“Work restarts, tasks that return to in-progress after moving to another stage, are up 13.8%.”

보고서가 '의도'를 직접 다루지는 않지만, 작업 재시작과 churn 급증은 AI 도입 뒤 변경이 되돌려지고 다시 만들어지는 재작업 비용을 대규모 텔레메트리로 보여 주는 2026년 수치다. 의도 부채가 낳는 결과를 뒷받침하는 정량 근거로 쓸 수 있다.

측정과 실증

Daniel Stenbergdaniel.haxx.se blog블로그영어

curl 창시자 Daniel Stenberg가 2019년 4월 HackerOne과 함께 시작한 버그 바운티를 2026-01-31에 종료한다고 알린 글이다. 2025년부터 AI 슬롭 리포트가 폭증해 실제 취약점으로 확인되는 비율이 크게 떨어졌고, 이를 가려내는 데 드는 시간과 에너지가 메인테이너를 소진시킨 것이 이유다. 앞으로 보고는 GitHub 비공개 취약점 보고나 security@curl.se로 받되 금전 보상은 없으며, AI 슬롭 제출자는 계속 즉시 차단한다.

“Previous years we have had a rate of somewhere north of 15% of the submissions ending up confirmed vulnerabilities. Starting 2025, the confirmed-rate plummeted to below 5%.”

설명·검증 책임이 없는 AI 산출물이 검토자에게 비용을 떠넘기는 구조를 확인율 하락이라는 구체적 수치로 보여 준다. 오픈소스 프로젝트가 AI 기여에 대응해 절차(보상 폐지, 제출자 차단)를 바꾼 사례로 쓸 수 있다.

측정과 실증강제 장치·기여 정책

Joel Becker, Nate Rush, Tom Cunningham, David Rein, Khalid Mahamud (METR)METR blog블로그영어

2025년 7월 발표한 경험 많은 오픈소스 개발자 대상 RCT(AI 사용 시 19% 느려짐, CI +2%~+39%)의 후속으로, 원래 참가자 10명과 신규 47명(총 57명)을 대상으로 2025년 하반기에 실험을 반복한 중간 보고다. 원래 참가자 집단은 AI 사용 시 -18%(CI -38%~+9%), 신규 참가자는 -4%(CI -15%~+9%)의 시간 변화를 보여 2025년 초보다 AI의 가속 효과가 커졌다고 보지만, AI 없이 하기 싫어 과제 제출을 피한 개발자가 30~50%에 이르고, 시급을 150달러에서 50달러로 낮췄으며, 에이전트 도구를 기다리며 다른 작업을 병행해 소요 시간 측정이 어려워진 선택 효과 때문에 이 데이터는 매우 약한 증거라고 명시한다. 이런 선택 효과의 심각성 때문에 실험 설계를 바꾸는 중이라고 밝힌다.

“However, because of the selection effects in our experiment, our data is only very weak evidence for the size of this increase.”

2025년 METR RCT의 '19% 느려짐'을 인용할 때 2026년 후속 실험에서 방향이 바뀌었을 가능성과 그 증거가 선택 효과로 매우 약하다는 점을 함께 적어야 하므로, AI 코딩 도구의 생산성 효과를 정직하게 소개하려면 반드시 같이 봐야 하는 1차 자료다. 에이전트 병행 작업으로 시간 측정 자체가 흔들린다는 관찰은 측정 연구의 한계를 보여준다.

측정과 실증

Stack OverflowStack Overflow Developer Survey보고서영어

2025년 Stack Overflow 개발자 설문의 AI 섹션이다. 응답자의 84%가 개발 과정에서 AI 도구를 쓰고 있거나 쓸 계획이고(전년 76%), 전문 개발자의 51%가 매일 쓴다. 반면 AI 도구에 대한 긍정 정서는 2023–2024년의 70% 이상에서 60%로 떨어졌고, AI 정확도를 불신한다는 응답(46%)이 신뢰한다는 응답(33%)보다 많다. 가장 큰 불만은 '거의 맞지만 완전히 맞지는 않은' AI 답변(66%)이고, 그다음은 AI가 생성한 코드를 디버깅하는 데 시간이 더 든다는 점(45.2%)이다.

“The biggest single frustration, cited by 66% of developers, is dealing with "AI solutions that are almost right, but not quite."”

AI가 내놓는 '거의 맞는' 답과 AI 코드를 디버깅하는 부담이 개발자들의 가장 큰 불만으로 드러나, 맥락 없이 생성된 코드가 검증·재작업 비용을 낳는다는 문제를 대규모 설문 수치로 뒷받침한다.

측정과 실증

William Harding (Lead Researcher & CEO) — Alloy.dev Research / GitClearGitClear AI Code Quality Research v2025.2.5 (published February 2025)보고서영어

2020년 1월부터 2024년 12월까지 커밋된 2억 1,100만 줄의 코드 변경을 GitClear의 분류(추가·삭제·수정·이동·복붙·찾아바꾸기·churn)로 분석한 보고서다. 리팩터링의 지표인 '이동(moved)' 줄 비율이 2020년 24.1%에서 2024년 9.5%로 떨어졌고 커밋 내 복사·붙여넣기는 8.3%에서 12.3%로 올라, 2024년은 복붙이 이동을 처음 앞지른 해가 됐다. 2주 내 재수정되는 churn은 3.1%에서 5.7%로, 5줄 이상 중복 블록을 포함한 커밋 비율은 0.70%(2020)에서 6.66%(2024)로 늘었으며 보고서는 이를 2년 전(2022년 0.45%) 대비 약 10배로 서술한다. 보고서는 코드 재사용이 새 팀원이 배워야 할 개념과 '함정'을 줄이는 반면, 중복 블록은 수정·리뷰 시 그 블록을 쓰는 모든 시스템을 파악해야 하는 부담을 만든다고 설명한다.

“Code reuse leaves fewer concepts (and “gotchyas”) for new team members to learn.”

리팩터링 대신 복붙이 늘어나는 추세는 같은 로직의 사본마다 '왜 다른가'를 설명해야 하는 부담을 만들고, 보고서 스스로도 중복 블록이 새 팀원과 리뷰어가 파악해야 할 맥락을 늘린다고 지적하므로, AI 생성 코드가 의도를 담지 못하게 되는 구조적 신호와 프런트엔드 컴포넌트 중복 점검 지표로 쓸 수 있다.

측정과 실증

Nathen Harvey, Derek DeBellis (DORA, Google Cloud)Google Cloud Blog보고서영어

2025년 9월 24일 공개된 DORA의 'AI 지원 소프트웨어 개발 현황' 보고서 발표 글로, 약 5,000명의 기술 전문가 설문과 100시간 이상의 질적 자료를 근거로 "AI는 팀을 고치지 않고 이미 있는 것을 증폭한다"고 결론짓는다. 응답자의 90%가 업무에 AI를 쓰고 80% 이상이 생산성 향상을 느끼지만 30%는 AI 생성 코드를 거의 또는 전혀 신뢰하지 않으며, AI 도입은 배포 처리량·제품 성과와는 양의 관계, 배포 안정성과는 여전히 음의 관계를 보인다. 보고서는 7가지 역량으로 구성된 DORA AI Capabilities Model과 7개 팀 아키타입을 제시하고, 리더에게 AI 정책 명확화, AI를 내부 맥락에 연결하기, 기초 실천 우선, 안전망 강화, 내부 플랫폼 투자, 최종 사용자 중심을 권고한다.

“AI doesn't fix a team; it amplifies what's already there. Strong teams use AI to become even better and more efficient. Struggling teams will find that AI only highlights and intensifies their existing problems.”

AI가 팀의 기존 약점을 증폭한다는 결론과 'AI를 내부 맥락에 연결하라'는 권고는, 프로젝트의 의도·결정 기록이 흩어져 있는 팀일수록 AI 도입 후 방향 이탈과 불안정이 커진다는 뜻이므로, 도입 전에 SSOT와 맥락 접근을 정비해야 한다는 주장의 산업 근거가 된다.

측정과 실증강제 장치·기여 정책조직 지식 검색

Kelly Hong, Anton Troynikov, Jeff Huber (Chroma)Chroma Research보고서영어

2025년 7월 14일 Chroma가 발표한 기술 보고서로, 18개 최신 모델에서 입력 길이가 늘수록 단순 과제에서도 성능이 떨어지는 '컨텍스트 부패(context rot)'를 실험으로 보였다. NIAH 확장(질문-정답 유사도, 방해 요소, 건초더미 구조), LongMemEval(집중 입력 대 전체 입력), 반복 단어 과제를 사용했다. 관련 정보가 컨텍스트에 있느냐보다 어떻게 제시되느냐가 더 중요하며, 가장 뛰어난 모델도 이에 민감하므로 효과적인 컨텍스트 엔지니어링이 필수라고 결론짓는다. 프로젝트 히스토리를 통째로 컨텍스트에 넣는 접근이 왜 실패하는지 보여주는 실증 근거다.

“What matters more is how that information is presented. We demonstrate that even the most capable models are sensitive to this, making effective context engineering essential for reliable performance.”

'왜'를 담은 결정 기록·히스토리를 에이전트 컨텍스트에 전부 밀어넣기보다 선별·구조화해서 제시해야 한다는 주장을 수치로 뒷받침한다. 의도 부채 해소를 위한 컨텍스트 엔지니어링·검색 기반 접근의 근거로 쓸 수 있다.

측정과 실증개념 틀과 이론

Chunhua Liu, Hong Yi Lin, Patanamon ThongtanunamarXiv (cs.SE)논문영어

언어 모델이 코드 변경을 자연어로 옮기는 두 과제인 커밋 메시지 생성과 코드 리뷰 코멘트 생성에서 환각이 얼마나 나타나는지 처음으로 종합 분석한 2025년 연구다. 생성된 코드 리뷰의 약 50%, 생성된 커밋 메시지의 약 20%에 환각이 포함됐다고 보고한다. 흔히 쓰는 지표는 단독으로는 약한 탐지기지만 여러 지표를 결합하면 성능이 크게 오르며, 모델 신뢰도와 특성 귀속 지표가 추론 시점 탐지에 유망하다고 제시한다.

“Our findings reveal that approximately 50% of generated code reviews and 20% of generated commit messages contain hallucinations.”

커밋 메시지는 변경 이유를 찾는 주요 기록이다. 이 연구의 수치대로라면 AI가 생성한 커밋 메시지를 검토 없이 남길 경우 다섯 건 중 한 건꼴로 사실과 다른 서술이 히스토리에 섞일 수 있으므로, 사람 검토나 자동 탐지 단계를 두는 근거로 쓸 수 있다.

측정과 실증커밋 히스토리·변경 출처

Anthropic (Saffron Huang, Bryan Seethor, Esin Durmus, Kunal Handa, Miles McCain, Michael Stern, Deep Ganguli)Anthropic Research보고서영어

2025년 12월 2일 공개된 Anthropic 자체 연구로, 엔지니어·연구자 132명 설문, 53건의 심층 인터뷰, 2025년 2월과 8월의 내부 Claude Code 트랜스크립트 20만 건을 분석했다. 직원들은 업무의 59%에 Claude를 쓰며(전년 28%), 자기보고 생산성 향상은 50%였고, Claude 지원 작업의 27%는 Claude가 없었다면 하지 않았을 일이었다. 매일 쓰는 용도로 디버깅 55%, 코드 이해 42%가 꼽혔고, 응답자 절반 이상이 완전히 위임할 수 있는 업무는 0~20%에 그친다고 답했다. 어려운 문제를 직접 디버깅하며 문서와 코드를 읽는 시간이 '시스템이 어떻게 동작하는지에 대한 모델'을 만드는 시간이었는데 그것이 줄었다는 인터뷰, 자신이 쓰지 않은 Claude 코드를 이해하는 데 인지 부담이 더 든다는 보고, Claude를 감독하려면 과다 사용으로 위축될 수 있는 바로 그 코딩 기술이 필요하다는 '감독의 역설(paradox of supervision)'이 기록돼 있다.

“If you were to go out and debug a hard issue yourself, you're going to spend time reading docs and code that isn't directly useful for solving your problem—but this entire time you're building a model of how the system works.”

AI 코딩 도구를 만드는 회사 내부에서도 직접 파고들며 쌓던 '시스템 모델'이 사라지고, 자신이 쓰지 않은 코드를 이해하는 부담이 커진다는 점을 설문·인터뷰·트랜스크립트로 기록한 1차 자료다. 의도 부채와 이해 부채가 도구 숙련도와 무관하게 생기는 문제임을 보여줄 때 인용할 수 있다.

측정과 실증이해 유지 실천

Joel Becker, Nate Rush, Beth Barnes, David Rein — METRMETR blog (arXiv:2507.09089)보고서영어

대규모 오픈소스 저장소(평균 22k+ 스타, 100만 줄 이상)에 평균 5년간 기여한 경험 많은 개발자 16명이 246개의 실제 이슈를 AI 허용·비허용 조건에 무작위 배정받아 수행한 RCT다. Cursor Pro와 Claude 3.5/3.7 Sonnet을 쓴 조건에서 완료 시간이 19% 더 걸렸으나, 개발자들은 사전에 24% 단축을 예상했고 사후에도 20% 빨라졌다고 믿었다. 저자들은 감속 요인 중 하나로 문서화·테스트 커버리지·린팅 같은 암묵적 요구사항이 많고 품질 기준이 높은 성숙한 저장소에서 AI가 그 맥락을 갖지 못한 점을 든다. 코드베이스의 암묵지가 에이전트에 전달되지 않을 때 드는 비용을 정량화한 사례로 인용된다.

“implicit requirements (e.g. relating to documentation, testing coverage, or linting/formatting) that take humans substantial time to learn”

암묵적 규칙이 많은 성숙한 저장소일수록 AI가 그 규칙을 모른 채 만든 코드를 다시 고치느라 느려진다는 점을 무작위 실험으로 보여주므로, 저장소의 규칙과 이유를 에이전트가 읽을 수 있게 문서화해야 한다는 근거로 삼을 수 있다.

측정과 실증

Joel Becker, Nate Rush, Elizabeth Barnes, David Rein (METR)arXiv (METR)논문영어

METR가 2025년 7월 공개한 무작위 대조 실험으로, 평균 5년간 기여해 온 성숙한 오픈소스 프로젝트에서 숙련 개발자 16명이 246개 과제를 AI 허용·불허 조건으로 수행했다. 개발자들은 AI로 완료 시간이 24% 줄 것으로 예상했고 사후에도 20% 줄었다고 느꼈지만, 실제로는 완료 시간이 19% 늘었다. 저자들은 20가지 요인을 검토한 뒤에도 감속 효과가 견고하다고 보고했으며, 본문에서 AI가 숙련자의 암묵지에 접근하기 어렵다는 점을 요인 중 하나로 논의한다. METR는 2026년 2월 24일 별도 블로그 글에서 실험 설계 변경을 알리며 기존 참가자 -18%(신뢰구간 -38%~+9%), 신규 참가자 -4%(-15%~+9%)의 속도 향상 추정치를 내놓았고, 선택 효과 때문에 실험에서 빠진 개발자·과제에서는 실제 속도 향상이 훨씬 클 수 있다고 덧붙였다.

“Surprisingly, we find that allowing AI actually increases completion time by 19%--AI tooling slowed developers down.”

코드베이스를 깊이 아는 숙련 개발자가 AI를 쓰자 오히려 느려졌고, 저자들은 AI가 그들이 가진 암묵지(적절한 수정 위치, 하위 호환 사정 등)에 접근하기 어려운 점을 요인으로 논의한다. 의도가 코드 밖에 암묵지로만 남아 있을 때 드는 비용을 보여 주는 실험적 근거다.

측정과 실증

Gergely Orosz (The Pragmatic Engineer)The Pragmatic Engineer 뉴스레터 (LDX3 London 키노트 정리, 2025-07-01)기사영어

LDX3 London 키노트를 정리한 글로, AI 개발 도구 회사, 빅테크, AI 스타트업 등이 LLM을 실제로 어떻게 쓰는지 사례로 살핀다. incident.io는 엔지니어링 문서를 담은 Claude Code 'Projects'를 만들어 자사 스타일·컨벤션·아키텍처 선호에 맞게 코드 초안을 쓰게 했다. 반면 한 바이오테크 AI 스타트업은 AI 리뷰 코멘트의 90%가 도움이 되지 않았다고 했고, '올바른 코드를 직접 쓰는 것이 LLM 코드를 리뷰하고 고치는 것보다 여전히 빠르다'고 답했다. 팀과 코드베이스에 따라 체감 성과가 크게 갈린다는 현장 관찰이다.

“Built Claude Code 'Projects' which contain our engineering documentation, so people can draft code in our style, according to our conventions and architecture preferences”

팀의 컨벤션과 아키텍처 문서를 에이전트에게 주는 팀(incident.io)과 AI 산출물의 효용이 낮다고 본 팀을 실제 사례로 대비할 수 있다. 다만 의도 부채를 직접 다룬 글은 아니고 간접적인 현장 근거다.

측정과 실증저장소 지시 파일강제 장치·기여 정책

Atlassian (Andrew Boyagi)Atlassian Blog (State of Developer Experience)보고서영어

2025년 7월 9일 공개된 Atlassian의 개발자 경험 보고서로, 6개국 3,500명의 개발자·관리자를 조사했다. 개발자의 50%가 주당 10시간 이상, 90%가 6시간 이상을 비코딩 작업으로 잃는다고 답했고, 주된 원인은 조직의 비효율이다. 가장 큰 낭비 원인으로는 서비스·문서·API 같은 정보 찾기, 새 기술 적응, 도구 간 컨텍스트 전환을 꼽았다. 반면 99%가 AI로 시간을 아끼고 68%는 주 10시간 이상 절약한다고 답해, AI로 번 시간을 조직 마찰이 다시 상쇄하는 구조를 지적한다.

“Developers report the top time-wasters as: finding information (services, docs, APIs), adapting new technology, and context switching between tools.”

AI가 벌어준 시간을 '정보 찾기'가 다시 삼킨다는 수치는 의도 부채의 비용을 시간 단위로 설명할 때 직접적인 근거가 된다.

측정과 실증강제 장치·기여 정책

Faros AI (Faros Research)Faros AI research blog보고서영어

1,255개 팀, 1만 명 이상 개발자의 텔레메트리를 2025년 6월 기준으로 분석해 2025년 7월 23일 공개한 산업 보고서다. AI 도입률이 높은 팀은 완료 과제가 21%, 병합된 PR이 98% 늘었지만 PR 리뷰 시간이 91%, 평균 PR 크기가 154%, 개발자당 버그가 9% 늘었다. 회사 수준의 처리량·DORA 지표·품질 KPI와 AI 도입 사이에는 유의한 상관이 없었으며, 팀 단위 이득이 조직 단위로 합산되지 않는다고 결론짓는다. 코드가 사람이 검토할 수 있는 속도보다 빨리 생성될 때 리뷰(이해) 단계가 병목이 된다는 점을 수치로 보여준다.

“AI adoption is consistently associated with a 9% increase in bugs per developer and a 154% increase in average PR size”

PR이 두 배로 늘고 리뷰 시간이 두 배로 느는 현상은 '이해 없이 병합되는 코드'가 쌓이는 경로 그 자체이므로, 팀에 리뷰 정책과 컨텍스트 문서를 요구할 때 근거 수치로 쓸 수 있다. 다만 보고서 자체는 의도 부채나 이해 부채를 직접 다루지는 않는다.

측정과 실증

Hao-Ping (Hank) Lee, Advait Sarkar, Lev Tankelevitch, Ian Drosos, Sean Rintel, Richard Banks, Nicholas Wilson — Microsoft ResearchCHI 2025 (ACM CHI Conference on Human Factors in Computing Systems)논문영어

지식노동자 319명이 제출한 936건의 생성형 AI 업무 사용 사례를 분석한 설문 연구다. 생성형 AI에 대한 신뢰가 높을수록 비판적 사고가 줄고, 자기 능력에 대한 자신감이 높을수록 비판적 사고가 늘어나는 상반된 효과를 보고한다. 또 생성형 AI가 비판적 사고의 성격을 정보 검증, 응답 통합, 과제 관리(task stewardship) 쪽으로 옮긴다고 정리한다.

“higher confidence in GenAI is associated with less critical thinking, while higher self-confidence is associated with more critical thinking”

AI 출력에 대한 신뢰가 높을수록 검토를 덜 한다는 결과는, AI가 만든 코드의 근거를 사람이 검토하지 않은 채 수용하면서 의도 부채가 쌓이는 심리적 경로를 설명한다. 리뷰에서 '왜 이렇게 했는가'를 묻는 절차를 팀 규칙으로 못 박아야 하는 근거가 된다.

측정과 실증이해 유지 실천

JetBrainsJetBrains State of Developer Ecosystem보고서영어

JetBrains가 2025년 4–6월에 개발자 24,534명을 조사한 연례 보고서의 AI 섹션이다. 개발자들은 단순 반복 작업은 AI에 맡기되 창의적이고 복잡한 작업은 직접 통제하고 싶어 하며, 직접 하겠다는 응답이 많은 과제에 디버깅(47%)과 코드 이해(43%)가 포함된다. AI에 대한 가장 큰 우려로는 생성 코드 품질(23%), AI 도구의 복잡한 코드·로직 이해 부족(18%), 컨텍스트 인식 부족(10%)이 꼽혔다. 기업의 AI 도입은 파일럿(27%)과 부분 도입(30%) 단계가 가장 많아, 핵심 워크플로에 완전히 통합된 경우는 아직 드물다고 정리한다.

“Developers would like to delegate mundane tasks to AI, but would prefer to stay in control of more creative and complex ones.”

대규모 개발자 설문에서 'AI의 복잡한 코드·로직 이해 부족'(18%)과 '컨텍스트 인식 부족'(10%)이 주요 우려로 집계되어, AI 도구가 코드의 맥락과 의도를 충분히 알지 못한다는 문제를 개발자들이 스스로 인식하고 있다는 정량 근거로 쓸 수 있다.

측정과 실증

Nataliya Kosmyna, Eugene Hauptmann, Ye Tong Yuan, Jessica Situ, Xian-Hao Liao, Ashly Vivian Beresnitzky, Iris Braunstein, Pattie Maes (MIT Media Lab 등)arXiv preprint 2506.08872 (v1 2025-06-10, v2 2025-12-31)논문영어

54명을 LLM·검색엔진·두뇌만 사용 세 집단으로 나눠 4개월간 4회의 에세이 작성 세션을 진행하고 EEG로 뇌 연결성을 측정한 연구로, 4회차에는 18명이 집단을 바꿔 참여했다. 1회차에서 LLM 집단의 83.3%(15/18)가 방금 쓴 에세이에서 정확한 인용을 하지 못한 반면 검색엔진·두뇌만 사용 집단은 각각 11.1%(2/18)에 그쳤고(p < .001), 뇌 연결성은 두뇌만 사용 집단이 가장 강하고 LLM 집단이 가장 약했으며, LLM 집단이 인터뷰에서 보고한 에세이 소유감은 낮았다. 논문은 '인지 부채(cognitive debt)'를 'LLM 같은 외부 시스템에 반복 의존하면서 독립적 사고에 필요한 노력스러운 인지 과정을 대체하는 상태'로 정의하고, 단기적으로는 정신적 노력을 미루지만 비판적 탐구 감소·조작 취약성 증가·창의성 저하 같은 장기 비용을 낳는다고 본다.

“cognitive debt, a condition in which repeated reliance on external systems like LLMs replaces the effortful cognitive processes required for independent thinking.”

'인지 부채'라는 용어를 정의하고 널리 퍼뜨린 출처이며, AI가 대신 만든 산출물을 방금 만들고도 기억·인용·소유하지 못하는 현상을 실험으로 보였다. 코드 도메인 연구는 아니지만 의도 부채의 인간 측 뿌리(산출물은 있는데 그 의도를 설명할 사람이 없는 상태)를 설명할 때 개념적 근거로 인용할 수 있다.

측정과 실증개념 틀과 이론

Nathen Harvey, Derek DeBellis (DORA / Google Cloud)Google Cloud Blog보고서영어

2024년 10월 23일 공개된 DORA 연례 보고서(Accelerate State of DevOps 2024) 발표문이다. 응답자의 75% 이상이 최소 하나의 일상 업무에서 AI에 의존한다고 답했다. AI 도입이 25% 늘어나면 문서 품질(+7.5%), 코드 품질(+3.4%), 코드 리뷰 속도(+3.1%)가 함께 개선되는 연관이 나타났다. 반면 배포 처리량은 1.5%, 배포 안정성은 7.2% 줄어든 것으로 추정됐다. 응답자의 39%는 AI 생성 코드를 거의 또는 전혀 신뢰하지 않는다고 답했다.

“As AI adoption increased, it was accompanied by an estimated decrease in delivery throughput by 1.5%, and an estimated reduction in delivery stability by 7.2%.”

AI 도입이 개인 생산성과 문서 품질을 높이는 동시에 팀 단위 배포 안정성은 떨어뜨린다는 업계 대규모 설문 수치다. 따라서 AI 보조 개발이 비용 없이 이득만 주지 않는다는 배경 근거로 인용할 수 있다. 다만 원인이 맥락 부족이라고 보고서가 밝힌 것은 아니다.

측정과 실증

Martin P. Robillard (McGill University)ESEC/FSE 2021 (DOI 10.1145/3468264.3473923)논문영어

세 회사의 전문 개발자·관리자 27명을 심층 인터뷰해 구성원 이탈로 인한 지식 손실이 어떤 맥락에서 일어나고 어떤 결과를 낳는지 정리한 질적 연구다. 참가자 25명이 설명한 41개 직장 상황에 지식 손실 맥락 프레임워크를 적용하고, 그 영향을 '지침·정보 부족', '문서 의존', '동료 의존', '지식 재생성'의 네 주제 20개 관찰로 종합했다. 설계 결정의 근거를 알 수 없어 코드의 의도를 추측해야 하고 "왜 이걸 무시했지?"를 되묻게 되는 사례를 들며, 설계 근거의 외재화가 악명 높게 어렵기 때문에 개발자가 지식을 다시 만들어내야 한다고 서술한다. Rigby 외의 정량적 지식 손실 모델링 연구를 잇는 현장 관점의 후속작이다.

“developers lacking a ground truth about the rationale for design decisions can also be left guessing the intent of the code: "It's been a while and most of the people who developed this have moved on”

AI 이전에도 사람이 떠나면 '왜'가 함께 사라진다는 것을 현장 목소리로 보여 주며, 문서·동료·이력 각각의 한계를 대비해 팀 온보딩과 근거 기록 설계에 쓸 수 있다.

측정과 실증강제 장치·기여 정책개념 틀과 이론

Margaret-Anne Storey, Alexey Zagalsky, Fernando Figueira Filho, Leif Singer, Daniel M. GermanIEEE Transactions on Software Engineering 43(2), pp. 185–204논문영어

GitHub 사용자 1,449명을 대규모로 설문해 개발자가 업무에 필수로 여기는 커뮤니케이션 채널과 그 채널을 쓰며 겪는 어려움을 조사한 논문이다. 소셜 도구가 늘면서 개발자가 서로 배우고 함께 만드는 '참여 문화'가 생기지만, 여러 채널을 함께 쓸 때 생기는 기회와 문제는 아직 잘 이해되지 않았다고 지적한다. 결과는 개발자와 도구 설계자에게 줄 권고의 경험적 기반으로 제시된다.

“However, the interplay of these social channels, as well as the opportunities and challenges they may create when used together within this participatory development culture are not yet well understood.”

개발 관련 소통이 여러 채널에 나뉘어 이루어지고 그 조합이 어려움을 만든다는 점을 설문 데이터로 보여 준다. 결정의 맥락이 코드 밖 여러 채널에 흩어져 다음 작업자나 에이전트가 찾기 어렵다는 의도 부채 문제의 배경 근거로 쓸 수 있다. 다만 이 연결은 이 페이지의 해석이며, 논문이 직접 주장한 내용은 아니다.

측정과 실증강제 장치·기여 정책

Andrew Begel, Beth SimonICER '08: Proceedings of the Fourth International Workshop on Computing Education Research논문영어

Microsoft에 입사한 지 6개월이 안 된 신입 개발자들을 2개월 동안 현장에서 따라다니며 관찰한 질적 사례 연구다. 코딩·디버깅·설계·팀과의 상호작용 등 업무 전반을 관찰하고 어떤 과제를 수행하는지 분석했다. 관찰된 행동의 상당 부분은 조직 관리 분야의 신입 사회화(newcomer socialization) 관점으로 설명된다. 저자들은 이를 바탕으로 대학과 산업 현장에서 신입이 전문가로 성장하는 과정을 앞당길 학습 절차를 논의한다.

“We can explain many of the behaviors revealed by our analyses if viewed through the lens of newcomer socialization from the field of organizational management.”

숙련된 학생도 조직에 들어가면 다시 신입이 되고, 그 적응 과정이 신입 사회화의 문제라는 점을 실증한 온보딩 연구다. 세션마다 맥락 없이 새로 시작하는 AI 에이전트를 매번 새로 들어온 신입으로 보는 비유를 뒷받침하는 배경 자료로 쓸 수 있다. 다만 이 비유는 이 페이지의 해석이며 논문이 직접 다룬 내용은 아니다.

측정과 실증강제 장치·기여 정책

Simon Willisonsimonwillison.net (2026-08-19), Talking Postgres 팟캐스트 "How AI is changing software development with Simon Willison" 발췌블로그영어

Simon Willison이 Talking Postgres 팟캐스트 발언을 정리한 글로, Brooks의 『맨먼스 미신』에 나오는 개념적 무결성—잘 설계된 소프트웨어에는 놀라움이 없고 딱 맞는 범위를 다룬다—을 코딩 에이전트 시대에 다시 꺼낸다. 에이전트가 기능 추가를 싸게 만들자 소프트웨어가 "이상한 혹"을 여러 방향으로 키우며 자라고, 예전에 일주일이 걸려 자연스럽게 걸러지던 기능이 "한 시간이면 되니까"로 정당화되면서 규율이 사라진다고 본다. Claire Giordano가 든 Winchester Mystery House(140개 방) 비유로 무계획 증식을 설명한다. 동시에 품질이 유지된다면 에이전트로 하루 1,000줄의 디버깅된 코드를 내는 것은 사람의 하루 50~60줄(아주 좋은 날 200줄) 대비 실질적 향상이라며, 제약 조건하에서 LoC 측정을 옹한다.

“well-designed software has an integrity to it ... there are no surprises in it, it covers exactly the right domain of things ... Your software grows little weird bumps in funny different directions.”

에이전트로 기능이 싸게 붙을수록 프로젝트 방향이 흐려지는 이유를 Brooks의 개념적 무결성이라는 오래된 언어로 설명하므로, '왜 이 기능을 넣지 않기로 했는가'와 범위 결정을 기록해야 하는 의도 부채의 이론적 근거로 쓸 수 있다. 또 코드 산출량이 아니라 인지 용량이 병목이라는 지적은 이해 부채(comprehension debt) 논의와 직접 이어진다.

개념 틀과 이론

Margaret-Anne Storey (University of Victoria)arXiv 2603.22106, cs.SE (v1 2026-03-23, v4 2026-04-06; 10 pages, 1 figure)논문영어

소프트웨어 건강을 기술 부채(코드), 인지 부채(사람—팀 차원 공유 이해의 침식), 의도 부채(비코드 아티팩트—명시적 근거·목표·제약의 부재나 침식)의 삼중 부채 모델로 다시 정의한다. 창업 수업의 한 학생 팀이 8주차에 정체했는데 아무도 설계 결정의 이유를 설명하지 못했고 Naur가 말한 시스템의 '이론'이 파편화되어 있었다는 사례로 시작한다. 의도는 결정 시점에 포착하는 것이 최선이며 나중에 복구하기는 어렵거나 불가능하고, AI 에이전트는 시스템이 '무엇을 하는가'뿐 아니라 '무엇을 위한 것인가'를 알아야 한다고 본다. 진단 신호(행동 드리프트, 에이전트가 맥락 부족으로 요점을 빗나가거나 토큰·시간을 과다 소모, 비기능 제약의 소실)와 처방(실행 가능한 의도인 BDD·테스트, ADR·DDD, 스킬·에이전트 지침·플레이북 같은 컨텍스트 아티팩트, 의도 우선 워크플로, 이해를 산출물로 취급, 이해의 자동화에 저항, 세 층 동시 모니터링)을 제시한다.

“Where technical debt lives in code and cognitive debt lives in people, intent debt lives in incomplete or missing non-code artifacts.”

이 프로젝트가 쓰는 '의도 부채' 용어의 직접적 출처이자 진단 신호와 처방까지 갖춘 학술 프레임워크이므로, 페이지의 정의와 분류 축(코드/사람/아티팩트)을 이 논문에 맞춰 두면 인용의 일관성을 확보할 수 있다. 특히 ADR·스펙·에이전트 지침 파일을 하나의 '의도 아티팩트' 범주로 묶는 근거가 된다.

개념 틀과 이론결정 기록(ADR)명세 주도 개발저장소 지시 파일강제 장치·기여 정책측정과 실증이해 유지 실천

Birgitta Böckeler (Thoughtworks)martinfowler.com (Exploring Gen AI series), 2026-04-02기사영어

코딩 에이전트를 둘러싼 설정 가능한 외곽을 'harness'로 보고, 에이전트가 행동하기 전에 방향을 잡는 feedforward '가이드'와 행동 뒤 자기 교정을 돕는 feedback '센서'로 나눈다. 린터·테스트 같은 결정론적(computational) 통제와 AI 코드 리뷰·'LLM as judge' 같은 추론적(inferential) 통제를 구분한다. 규제 대상을 유지보수성, 아키텍처 적합성, 기능 동작의 세 harness로 정리한다. 에이전트에게는 '여기서는 그렇게 하지 않는다'는 직관과 조직의 기억이 없다는 점을 harness가 필요한 이유로 든다.

“A coding agent has none of this: no social accountability, no aesthetic disgust at a 300-line function, no intuition that 'we don't do it that way here,' and no organisational memory.”

에이전트에게 조직의 기억이 없다는 점을 문제로 짚고, CLAUDE.md 같은 가이드와 린터·구조 테스트·훅 같은 센서를 한 틀로 묶어 드리프트를 막는 설계 지도를 준다.

개념 틀과 이론강제 장치·기여 정책저장소 지시 파일

Margaret-Anne Storey (University of Victoria, Canada Research Chair in Human and Social Aspects of Software Engineering)margaretstorey.com (personal blog)블로그영어

빅토리아 대학교 교수 Margaret-Anne Storey가 2026년 2월 9일에 쓴 블로그 글이다. 기술 부채는 코드에 쌓이지만, 빠른 속도로 개발하며 생긴 인지 부채는 개발자의 머릿속에 쌓인다고 설명한다. Naur의 '프로그램은 이론이다' 개념을 근거로 들고, 팀의 누구도 특정 설계 결정의 이유를 설명하지 못하게 된 학생 팀 사례를 소개한다. 대응책으로 AI가 만든 변경은 배포 전에 팀원 중 최소 한 명이 완전히 이해하게 할 것, 무엇이 바뀌었는지뿐 아니라 왜 바뀌었는지도 기록할 것, 코드 리뷰·회고·지식 공유 세션을 둘 것을 제안한다.

“no one on the team could explain why certain design decisions had been made or how different parts of the system were supposed to work together.”

AI 에이전트가 사람의 이해보다 빨리 코드를 만들어 설계 결정의 '왜'가 사라지는 문제를 소프트웨어공학 연구자가 직접 정의한 글이다. 그래서 의도 부채 문제를 설명하고 팀을 설득할 때 개념적 출발점으로 쓸 수 있다. 결정의 이유를 기록하라는 권고는 이 프로젝트의 SSOT 방향과도 직접 맞닿는다.

개념 틀과 이론이해 유지 실천강제 장치·기여 정책결정 기록(ADR)

Sean Goedeckeseangoedecke.com (2026-04-03)블로그영어

Sean Goedecke가 2026년 4월 3일에 쓴 글로, Peter Naur의 1985년 '이론 구축으로서의 프로그래밍'을 AI 에이전트 시대에 적용한다. 엔지니어링 작업의 일차 산출물은 코드가 아니라 엔지니어의 머릿속에 있는 시스템에 대한 이론이며, 에이전트는 세션 간에 코드베이스의 이론을 보존하지 못해 실행될 때마다 처음부터 다시 구성해야 한다고 본다. 저자는 에이전트 출력이 자기 이론에 맞지 않는 경우가 약 80%이고 실제로 자기 결과물에 들어가는 것은 약 10%뿐이며, 거의 모든 시간을 생성된 코드가 자기 이론에 맞는지 판단하는 데 쓴다고 밝힌다. 다만 에이전트도 한 세션 안에서는 가설 검증과 디버깅으로 이론을 구축하며, 가중치 수정이나 몇 주 분량의 변경을 담을 만큼 긴 컨텍스트가 지원되면 장기적으로 이론을 보존할 수 있으리라고 전망한다.

“they can't retain theories of the codebase. They have to build their theory from scratch every time.”

에이전트가 세션마다 코드베이스의 이론을 잃는다는 관찰은 같은 실수가 반복되고 변경이 프로젝트 방향에서 이탈하는 이유를 Naur의 이론 개념으로 설명하며, 사람이 시스템 이론을 붙들고 검토자로 남아야 한다는 실무 워크플로의 근거가 된다. 다만 글은 '의도 부채'라는 용어를 쓰지 않으며, 세션 간 지속 메모리와 긴 컨텍스트를 해법의 방향으로 제시한다.

개념 틀과 이론에이전트 메모리이해 유지 실천

Addy Osmaniaddyosmani.com (2026-06-05)블로그영어

Storey의 삼중 부채 모델을 실무자 관점에서 풀어쓴 글로, 의도 부채를 시스템이 왜 지금의 모습인지 설명하는 외부화된 근거·목표·제약의 부재 또는 침식으로 정의한다. 이해 부채가 '코드가 존재한다고 옳다고 믿지 말라'는 경고라면 의도 부채는 '코드가 남아 있다고 이유도 남아 있다고 믿지 말라'는 경고라는 비대칭을 제시한다. 에이전트는 의도를 생성할 수 없으며 의도는 사람이 넣어야 하는 유일한 입력이라고 본다. 실천으로 목표·제약을 담는 스펙, 의도 장부로서의 AGENTS.md, 결정 시점의 경량 ADR, 에이전트 학습 파일의 피드백 루프를 권한다.

“Comprehension debt warns you not to trust that code is correct because it exists. Intent debt warns you not to trust that the reason survives because the code does.”

AGENTS.md·CLAUDE.md를 설정 파일이 아니라 '왜'의 장부로 쓰라는 구체적 지침과 함께, 에이전트가 의도를 생성할 수 없다는 점을 분명히 하여 지침 파일과 결정 기록을 정비할 때 바로 참고할 수 있다.

개념 틀과 이론저장소 지시 파일결정 기록(ADR)명세 주도 개발에이전트 메모리

Brett WheelerarXiv preprint (cs.SE, cs.AI; position paper, 2026-06-18 제출)논문영어

트럭 팩터, Degree-of-Authorship, degree-of-knowledge 모델 같은 지식 집중 지표는 '코드 영역을 저술했다면 그것을 이해한다'는 하나의 추론 위에 서 있다고 지적한다. AI가 모듈을 생성하고 인간이 병합하면 버전 관리 기록은 여전히 저자를 귀속시키지만 그 귀속은 이해에 대해 아무 결론도 보증하지 못하며, 같은 코드 발자국이 완전한 이해·부분 이해·무이해 모두와 양립한다고 주장한다. 따라서 저자성 지표를 다듬는 것으로는 해결되지 않으며 이해의 증거에 기반한 대체 지표가 필요하다고 보고, 저자성 기준 트럭 팩터는 건강하지만 이해 측정치가 낮은 시스템이 인시던트 해결 실패를 겪을 것이라는 반증 가능한 예측을 제시한다. 10페이지 position paper로, 대체 지표의 구체적 구축은 미해결 과제로 남긴다.

“the version-control record still attributes authorship, but the attribution no longer licenses any conclusion about comprehension”

git blame이나 기여 통계로 '누가 이 코드를 아는지'를 판단하던 관행이 에이전트 시대에 왜 틀리는지 설명하므로, 의도 부채를 저자성으로 추정하려는 시도를 피하고 이해의 증거를 직접 기록·측정해야 한다는 근거가 된다.

개념 틀과 이론측정과 실증커밋 히스토리·변경 출처

Adam Greenoughadamgreenough.net (2026-08-31 게시, 2026-09-03 갱신)블로그영어

체스터튼의 울타리 원칙(왜 있는지 알기 전에는 치우지 말라)을 AI 생성 코드에 적용한 글이다. AI가 만든 코드는 커밋 메시지·주석·대화 기록 같은 서류 흔적이 거의 없고, 형식과 이름·패턴이 그럴듯해 누군가 깊이 생각한 것처럼 보이지만 실제로는 찾아낼 의도 자체가 적을 수 있다고 지적한다. 자신 있게 뜯어내는 실패와 두려워서 그대로 두는 실패라는 두 가지 잘못된 대응을 짚는다. AI는 코드 고고학에는 빠른 동료처럼 쓸 만하지만 아무도 기록하지 않았거나 애초에 없었던 의도를 복구할 수는 없으므로, 최종 판단은 사람이 맡고 치우기 전에 울타리 뒤를 살펴보라고 권한다.

“It can't magically recover an intention that nobody recorded, or that might never have existed at all.”

'이유를 모르는 코드는 지우지 않는다'는 규칙이 AI 코드에서는 이유 자체가 없거나 기록되지 않았을 수 있다는 점 때문에 흔들린다는 것을 보여 준다. 의도 부채 관점에서, 사람이 내린 결정과 에이전트가 만든 결정을 구분하고 AI와의 대화·근거를 흔적으로 남기는 습관의 필요성을 뒷받침한다.

개념 틀과 이론커밋 히스토리·변경 출처이해 유지 실천

Pol Alvarez Vecino (Answer.AI)Answer.AI 블로그 (2026-08-19)블로그영어

Naur의 이론 구축 관점을 따라 '프로그램은 그것을 만들고 유지하는 사람들이 가진 이론'이고 코드와 문서는 그 하류 산출물이며, LLM은 사람 머릿속에 있는 이 이론에 거의 접근하지 못하기 때문에 코드를 진짜로 단순화할 수 없다고 주장한다. 코드 줄 수나 순환 복잡도는 이론의 복잡도를 재지 못하며, OpenAI·Anthropic 클라이언트 클래스를 하나로 합치면 지표는 좋아지지만 다음 달 Anthropic 지원을 중단할 예정이라면 분리해 두는 편이 낫다는 예를 든다. Answer.AI 결제 시스템에서 Stripe 구독+크레딧 설계를 버리고 저장 카드 충전만 남긴 약 300줄 구현에 도달했으나, 인도 카드가 off-session 결제를 지원하지 않는 제약이 드러나자 GPT 5.5는 "Stripe 구독을 쓰라"는, 이미 버린 설계로 되돌리는 답을 냈고 팀은 이론의 단순함을 지키기 위해 인도 사용자에게 수동 충전을 요구하는 쪽을 택했다고 보고한다.

“Code and documentation are downstream artifacts of that Theory, and can never capture it completely. LLMs so far have little to no access to this information because it lives in people's minds.”

'버린 대안'과 '비즈니스 제약'이 기록되지 않으면 LLM이 이미 폐기한 설계를 다시 제안하는 실제 사례를 보여 주므로, 거부한 대안과 제약을 결정 기록에 남겨야 하는 이유를 구체적으로 설득할 수 있다.

개념 틀과 이론이해 유지 실천

홍승협(준이아빠)digitalmarketer.co.kr Insights기사한국어

국내에서 '의도 부채'라는 용어를 정면으로 다룬 글이다. arXiv 논문 'From Technical Debt to Cognitive and Intent Debt'를 출처로 들어 기술 부채, 인지 부채, 의도 부채를 구분하고, 의도 부채를 시스템 발전을 안내하는 명시적 근거·목표·제약이 없거나 사라진 상태로 설명한다. 의도는 결정하는 순간에 적지 않으면 대체로 사라진다고 강조하며, 사람이 하는 코드 리뷰, 남이 쓴 코드를 설명해 보기, 회고, 결정 기록과 명세, 에이전트가 읽을 수 있는 지침 문서를 처방으로 제시한다.

“의도는 결정하는 그 순간에만 붙잡을 수 있습니다. 코드는 나중에 정리할 수 있지만 왜 그렇게 정했는지는 그때 적지 않으면 대체로 사라집니다.”

이 프로젝트가 쓰는 '의도 부채'라는 말이 이미 한국어로 쓰이고 있음을 보여 준다. 학술 정의와 처방을 한국어로 소개하는 입문 자료로 쓸 수 있다.

개념 틀과 이론결정 기록(ADR)이해 유지 실천저장소 지시 파일

Andrej Karpathy / Y CombinatorYC AI Startup School, San Francisco (2025-06-17); Y Combinator Startup Library발표영어

소프트웨어 1.0(코드)·2.0(신경망 가중치)·3.0(자연어 프롬프트로 LLM을 프로그래밍)이라는 틀로 소프트웨어의 변화를 정리한 기조강연이다. LLM을 사람의 확률적 시뮬레이션인 '사람 영혼(people spirits)'으로 보되, 세션 간 지식이 축적되지 않는 '전향성 기억상실(anterograde amnesia)'과 컨텍스트 윈도우가 곧 작업기억이라는 인지적 한계를 지적한다. 그래서 생성은 AI가, 검증은 사람이 맡는 루프와 '자율성 슬라이더'를 갖춘 부분 자율(partial autonomy) 앱을 권하고, 문서를 llms.txt·마크다운·gitingest·DeepWiki처럼 에이전트가 읽을 수 있는 형태로 만들자는 'build for agents'를 제안한다.

“They also kind of suffer from anterograde amnesia.”

에이전트가 왜 프로젝트의 맥락과 의도를 스스로 기억하지 못하는지, 그래서 왜 저장소 안에 에이전트가 읽을 수 있는 문서를 둬야 하는지를 가장 널리 인용되는 언어로 설명해 주어 의도 부채 논의의 출발점과 팀 설득 자료로 쓸 수 있다.

개념 틀과 이론저장소 지시 파일에이전트 메모리

Simon Willison (quoting Tobi Lütke and Andrej Karpathy)Simon Willison's Weblog블로그영어

2025년 6월 27일 사이먼 윌리슨이 Shopify CEO 토비 뤼트케와 안드레이 카파시의 트윗을 인용해 '프롬프트 엔지니어링' 대신 '컨텍스트 엔지니어링'이라는 용어가 등장한 순간을 기록한 글이다. 뤼트케는 이를 'LLM이 과제를 그럴듯하게 풀 수 있도록 모든 컨텍스트를 제공하는 기술'로, 카파시는 '컨텍스트 창을 꼭 맞는 정보로 채우는 섬세한 기술이자 과학'으로 정의하며 태스크 설명·few-shot 예시·RAG·멀티모달 데이터·도구·상태와 이력·컴팩션을 그 구성 요소로 든다. 윌리슨은 프롬프트 엔지니어링이 '챗봇에 글자를 치는 일'로 오해된 경험을 들어, 사람들이 추론하는 정의가 결국 살아남는다며 용어 전환을 지지한다.

“the art of providing all the context for the task to be plausibly solvable by the LLM”

이후 도구 문서와 발표가 전제하는 '컨텍스트 엔지니어링'의 원 정의를 담은 1차 자료다. 카파시가 열거한 구성 요소(태스크 설명·RAG·상태와 이력 등)에 결정 기록과 제약이 자연스럽게 포함되므로, 코드베이스의 '왜'를 에이전트에게 넘기는 일이 이 개념의 대상임을 근거 있게 주장할 수 있다.

개념 틀과 이론

Walden Yan (Cognition)Cognition blog블로그영어

2025년 6월 12일 Cognition(Devin 개발사)의 월든 얀이 쓴 글로, 에이전트 신뢰성의 핵심을 컨텍스트 엔지니어링으로 규정하고 두 원칙을 제시한다. 첫째 "컨텍스트를 공유하되 개별 메시지가 아니라 전체 에이전트 추적을 공유하라", 둘째 "행동에는 암묵적 결정이 담기며 충돌하는 결정은 나쁜 결과를 낳는다"이다. 병렬 서브에이전트가 서로 모르는 가정 위에서 작업해 결과가 어긋나는 예(플래피 버드 클론)를 들고, 긴 작업에서는 행동·대화 이력을 "핵심 세부·사건·결정"으로 압축하는 전용 LLM을 제안한다. 결정이 행동 안에 암묵적으로 묻힌다는 원칙은 사람과 에이전트 사이의 의도 부채를 간명하게 정식화한 문장이다.

“Actions carry implicit decisions, and conflicting decisions carry bad results”

에이전트가 내린 결정이 행동(코드)에만 남고 이유는 사라지는 현상을 정식화한 글이라, 팀의 "결정을 기록하라" 규칙과 컨텍스트 공유 원칙을 세울 때 인용하기 좋다.

개념 틀과 이론에이전트 메모리

Drew Breunigdbreunig.com블로그영어

2025년 6월 22일 글로, 긴 컨텍스트가 실패하는 네 가지 양상을 정의하고 공개 연구 사례로 뒷받침한다. 컨텍스트 오염(환각이나 오류가 컨텍스트에 들어가 반복 참조됨), 산만(컨텍스트가 너무 길어 모델이 학습된 지식보다 컨텍스트에 과도하게 집착함), 혼동(불필요한 내용이 저품질 응답을 만듦), 충돌(축적된 정보와 도구가 서로 모순됨)이다. 후속 글 'How to Fix Your Context'(6월 26일)는 RAG, 도구 로드아웃, 컨텍스트 격리, 가지치기, 요약, 오프로딩 여섯 가지 대응책을 제시한다. 의도 부채 관점에서는 낡거나 상충하는 결정 기록을 무작정 컨텍스트에 넣으면 충돌과 혼동으로 오히려 성능이 떨어진다는 경고가 핵심이다.

“as the context grew significantly beyond 100k tokens, the agent showed a tendency toward favoring repeating actions from its vast history rather than synthesizing novel plans”

CLAUDE.md나 결정 로그를 키우기 전에 '컨텍스트 자체도 부채가 된다'는 네 가지 실패 양상을 먼저 알아야 한다. 의도를 전달하는 문서도 선별·요약·격리 없이 쌓이면 오염과 충돌의 원인이 된다.

개념 틀과 이론조직 지식 검색

Nicolli Rios, Manoel Gomes de Mendonça Neto, Rodrigo Oliveira SpínolaInformation and Software Technology, vol. 102, pp. 117–145 (Elsevier)논문영어

2012년부터 2018년 3월까지 발표된 기술 부채(TD) 2차 연구 13편을 다섯 개 연구 질문으로 종합한 3차 연구다. 기술 부채 유형의 분류 체계(taxonomy)를 발전시키고, 프로젝트에서 부채 항목이 발견되는 상황 목록과 부채 관리 활동·전략·도구의 현황 지도를 정리했다. 저자들은 TD라는 용어가 제품·개발 과정의 온갖 장애물에 붙어 쓰이면서 생기는 혼란과 모호성을 문제로 지적한다. AI 이전의 일반 기술 부채 연구이므로 의도 부채를 기존 부채 분류 체계와 연결해 설명할 때의 이론적 배경 자료로만 쓸 수 있다.

“We evolved a taxonomy of TD types, identified a list of situations in which debt items can be found in software projects, and organized a map representing the state of the art of activities, strategies and tools to support TD management.”

의도 부채를 팀에 소개할 때 기존 기술 부채 분류 체계와 관리 도구·언어에 연결해 설명할 수 있는 학술적 배경이다. 다만 이 논문은 AI 코딩 이전의 일반 TD 연구이며, 의도·근거 손실을 직접 다루지는 않으므로 보조 근거로만 인용한다.

개념 틀과 이론

Guilherme Avelino, Leonardo Passos, Andre Hora, Marco Tulio ValenteICPC 2016 (24th International Conference on Program Comprehension); arXiv:1604.06766논문영어

트럭 팩터(TF)를 '프로젝트가 마비되기 전까지 트럭에 치이거나(또는 그만두어) 사라져도 되는 최소 개발자 수'로 정의하고, 이를 자동으로 산정하는 새로운 접근법을 제안한다. GitHub 인기 프로젝트 133개에 적용해 대다수(65%)가 TF 2 이하임을 보였다. 67개 시스템의 개발자 설문에서 유효 응답의 84%가 산정된 TF 저자가 주요 저자임에 동의 또는 부분 동의했고, 53%가 산정된 TF 값에 긍정 또는 부분 긍정으로 답했다. 지식이 소수 개발자에게 집중되는 정도를 수치화한 대표 연구다.

“Truck Factor (TF) is a metric proposed by the agile community as a tool to identify concentration of knowledge in software development environments.”

프로젝트 히스토리와 맥락을 아는 사람이 팀에 고르게 분포하지 않는 문제를 '133개 프로젝트 중 65%가 트럭 팩터 2 이하'라는 수치로 보여준다. 지식 집중을 저장소 저자성에서 자동으로 측정하는 방법의 기준점이며, 의도가 소수의 머릿속에만 있을 때의 위험을 근거로 제시할 때 인용할 수 있다.

개념 틀과 이론측정과 실증커밋 히스토리·변경 출처

Allen H. Dutoit, Raymond McCall, Ivan Mistrík, Barbara Paech (편)Springer Berlin, Heidelberg책영어

설계 근거(design rationale) 연구를 소프트웨어 공학 전반으로 확장해 정리한 2006년 Springer 편저다. 소프트웨어 공학이 여전히 사람의 결정에 좌우되는 활동이라는 전제에서, 설계·개발 결정을 관련된 모든 이해관계자에게 명시적으로 만드는 것을 '근거 관리(rationale management)'로 정의한다. 근거 접근법의 역사적 개관 뒤에 근거 관리의 근본 문제와 해법, 요구공학, 소프트웨어 아키텍팅, 재사용 가능한 지식 조직화의 네 부로 구성되며, 1부에는 근거 포착의 장벽을 다룬 Horner & Atwood의 "Effective Design Rationale: Understanding the Barriers" 장이 실려 있다.

“Rationale management is concerned with making these design and development decisions explicit to all stakeholders involved.”

왜 결정 근거의 문서화가 반복해서 실패하는지에 대한 연구 축적을 한 권에서 훑을 수 있어, AI 에이전트가 읽을 결정 기록·의도 문서를 팀 프로세스로 설계하기 전에 참고할 만한 기준서다.

개념 틀과 이론결정 기록(ADR)강제 장치·기여 정책

David Lorge Parnas (McMaster University)ICSE-16 (16th International Conference on Software Engineering), Invited Plenary Talk, IEEE, 1994논문영어

소프트웨어 노화의 두 원인을 '변화의 부재(lack of movement)'와 '무지한 수술(ignorant surgery)'로 구분한다. 설계자는 단순한 개념을 염두에 두고 프로그램을 쓰지만, 그 개념을 모르는 사람이 변경하면 구조가 거의 항상 퇴화하고, 이런 변경이 반복되면 원 설계자도 변경자도 아무도 제품을 이해하지 못하게 된다. 6.2절은 설계 원칙과 결정이 미래 유지보수자에게 유용한 형태로 기록되지 않는 문제, '코드가 곧 문서'라는 태도, 계약용 공식 문서와 실제 문서라는 '두 벌의 장부' 현상을 비판하고, 변경을 위한 설계·기록 유지·회고적 문서화·"문서화되지 않았으면 끝난 것이 아니다"를 처방한다. 설계 개념 없이 코드를 고치는 AI 에이전트의 편집은 이 글이 말한 무지한 수술의 자동화로 읽을 수 있다.

“After many such changes, the original designers no longer understand the product. Those who made the changes, never did. In other words, nobody understands the modified product.”

'아무도 이해하지 못하게 되는' 붕괴가 변경자의 무지에서 온다는 Parnas의 진단은, 에이전트가 편집하기 전에 설계 개념과 결정 기록을 읽게 해야 하는 이유를 30년 전 언어로 정확히 설명한다. 6.2절의 '기록되지 않은 설계 결정'과 '두 벌의 장부'는 의도 부채의 원형이며, AI 에이전트의 SSOT·결정 기록 접근을 정당화하는 고전적 근거로 인용할 수 있다.

개념 틀과 이론결정 기록(ADR)강제 장치·기여 정책

Ward CunninghamOOPSLA '92 Experience Report (ACM), c2.com 게재본보고서영어

기술 부채 은유가 처음 등장한 경험 보고서다. 처음 출하하는 코드는 빚을 지는 것과 같고, 재작성으로 곧 갚으면 개발이 빨라지지만 갚지 않으면 '딱 맞지 않는 코드'에 쓰는 매 분이 이자로 누적되며, 통합되지 않은 구현의 부채는 엔지니어링 조직 전체를 멈춰 세울 수 있다고 말한다. 커닝햄은 2011년 영상 전사본인 c2 위키 'Ward Explains Debt Metaphor'에서 이 은유가 나쁜 코드가 아니라 프로그램과 당시의 이해가 어긋난 상태를 뜻했다고 설명했는데, 이는 코드가 결정의 의미를 반영하지 못하는 의도 부채의 정의와 가장 가깝다.

“Shipping first time code is like going into debt. A little debt speeds development so long as it is paid back promptly with a rewrite. Objects make the cost of this transaction tolerable.”

'부채'라는 말을 쓸 때 원저자가 뜻한 것이 코드 품질 저하가 아니라 코드와 이해의 불일치였다는 점을 확인하면, 의도 부채가 기술 부채의 변종이 아니라 원래 의미의 복원임을 팀에 설명할 수 있다. 후속 설명의 출처는 http://c2.com/wiki/remodel/pages/WardExplainsDebtMetaphor 이다.

개념 틀과 이론

Allan MacLean, Richard M. Young, Victoria M. E. Bellotti, Thomas P. Moran (Rank Xerox EuroPARC)Human–Computer Interaction 6(3–4), 201–250논문영어

설계 근거(design rationale)를 표현하는 접근인 설계 공간 분석(Design Space Analysis)과 그 반형식 표기 QOC를 제안한 논문이다. 핵심 설계 쟁점을 드러내는 질문(Questions), 그에 대한 가능한 답인 대안(Options), 대안을 평가·비교하는 기준(Criteria)으로 산출물 주변의 설계 공간을 표현하며, 설계 과정의 기록이 아니라 산출물과 나란히 구축하는 설계의 공동 산물(coproduct)이라고 규정한다. 저자들은 이 분석이 변경의 결과를 추론하는 명시적 표현이 되고, 설계팀 구성원 사이 또는 원 설계자와 이후 유지보수자 사이의 의사소통 수단이 되어 재설계와 재사용을 돕는다고 본다. NAVER LABS Europe(옛 Rank Xerox EuroPARC)의 연구사 페이지는 이 연구가 "최종 산출물은 설계자의 결정을 담고 있지만 그 결정에 이른 사고와 추론은 전혀 보존하지 않는다"는 문제의식에서 출발했다고 설명한다.

“serving as a vehicle for communication, for example, among members of the design team or among the original designers and later maintainers of a system”

ADR의 '고려한 대안'과 '결정 기준' 항목의 학문적 뿌리이며, 결정 근거를 토론 로그가 아니라 산출물과 함께 유지하는 정리된 표현으로 남겨야 이후 유지보수자(사람이든 AI 에이전트든)가 변경의 결과를 추론할 수 있다는 의도 부채의 원형적 문제의식을 보여준다.

개념 틀과 이론결정 기록(ADR)

Jeff Conklin, Michael L. Begeman (MCC Software Technology Program)ACM Transactions on Office Information Systems 6(4), 303–331, October 1988논문영어

Rittel의 IBIS(Issue–Position–Argument) 방법을 그래픽 하이퍼텍스트 도구로 구현해 설계 초기의 숙의를 포착하려 한 설계 근거(design rationale) 연구의 고전이다. 설계 근거를 "설계 문제, 나중에 기각된 것을 포함한 대안, 대안 간 트레이드오프 분석, 잠정·확정 결정의 기록"으로 정의하고, 요구사항·명세·회의록 등 모든 문서를 통합하는 중심(Design Journal)으로 삼자고 제안한다. 1년간의 시험 사용 통계와 함께, 문제가 아직 모호한 단계에 생각을 이슈·입장·논거로 쪼개는 인지 오버헤드가 "금지적(prohibitive)"이라는 점과, 채택된 입장에 표시만 해서는 채택 근거가 충분히 남지 않는다는 점을 보고해 '기록 비용'이라는 의도 부채의 근본 원인을 1988년에 이미 짚었다.

“the cognitive overhead required to segment the "muck" into discrete thoughts, identify their types, label them, and link them is prohibitive.”

ADR이나 why 로그를 도입할 때 부딪히는 "기록이 부담스러워 안 남는다" 문제의 원형과 최초의 도구적 해법 시도를 확인할 수 있다.

개념 틀과 이론결정 기록(ADR)

Peter NaurMicroprocessing and Microprogramming 15(5), 1985 (원 게재); 재수록 Computing: A Human Activity (1992), Alistair Cockburn, Agile Software Development 부록 B pp. 393–405 (열람한 PDF — 이 사본에는 1985년 집필과 1992년 재수록만 표기)논문영어

프로그래밍의 본질은 프로그램 텍스트 생산이 아니라 프로그래머가 문제와 해법에 대한 '이론'(Ryle의 의미)을 형성하는 활동이며, 문서는 "auxiliary, secondary product"에 불과하다고 주장한다. 이 이론은 문서를 최소 세 영역에서 초과한다: 프로그램 각 부분이 현실 세계의 어떤 활동과 대응하는지 설명하는 능력, 각 부분이 왜 그렇게 되어 있는지 정당화하는 능력, 수정 요구에 건설적으로 응답하는 능력이다. 이론을 가진 팀이 해체되면 프로그램은 '죽고', 문서만으로 이론을 되살리는 것은 '엄밀히 불가능'하다고 본다. 전체 문서·주석 코드·설계 토론을 넘겨받고도 기존 컴파일러 구조를 살리지 못한 그룹 B 사례를 통해, 코드와 문서만으로는 '왜'가 전달되지 않는다는 의도 부채의 원형을 정식화한 글이다.

“program revival, that is reestablishing the theory of a program merely from the documentation, is strictly impossible.”

CLAUDE.md·ADR·주석이 아무리 많아도 '왜'의 최종 근거는 사람의 이론에 있다는 점을 이해해야, 에이전트에게 무엇을 문서로 넘기고 무엇을 사람이 붙들어야 하는지 선을 그을 수 있다. 문서만으로 이론을 복원할 수 없다는 주장은 AI 에이전트가 문서·코드만 읽고 수정할 때 방향이 어긋나는 현상의 이론적 설명이 된다.

개념 틀과 이론강제 장치·기여 정책