AI 코딩 에이전트의 코드 수정을 막는 DESIGN.md 작성법

DESIGN.md의 정의와 AGENTS.md가 다루지 않는 범위

DESIGN.md는 저장소 루트에 위치한 마크다운 파일로, AI 코딩 에이전트에게 코드 구조가 왜 현재와 같은 형태인지 설명합니다. AGENTS.md는 이와 다른 질문에 답합니다. 즉, 빌드 명령어, 테스트 명령어, 통과해야 하는 린트 규칙, 수정해서는 안 되는 경로 등 이곳에서 작업하는 방법을 다룹니다. DESIGN.md는 이미 확정된 결정 사항과, 그 결정이 번복될 경우 무엇이 손상되는지를 기록합니다.

코딩 에이전트란 Claude Code나 Cursor처럼 저장소를 스스로 읽고 수정하는 도구를 의미하며, 기본적으로 자신감이 넘칩니다. 에이전트는 인식하지 못하는 패턴을 발견하면 이를 개선하려 합니다. 모델이 학습한 대부분의 코드에서 캐시는 Redis(인메모리 데이터 저장소)로 구현되므로, 직접 작성한 캐시를 Redis로 교체해 버릴 수 있습니다. AGENTS.md는 이를 막지 못합니다. 왜냐하면 make test는 어떤 경우에도 통과하기 때문입니다. 위반된 규칙이 에이전트가 읽을 수 있는 곳에 기록되어 있지 않았던 것입니다.

아직 첫 번째 파일을 작성하지 않았다면, 거기서부터 시작하십시오. AGENTS.md와 그 옆에 위치한 HUMAN.md에서 형식과 각 도구가 파일을 찾는 위치를 다룹니다. 이어지는 내용은 그 다음 장입니다.

DESIGN.md 파일의 실제 내용

형식을 가장 빠르게 배우는 방법은 기업들이 스스로 공개한 파일을 읽어보는 것입니다. 저장소 official-design-md는 그러한 파일들만을 추적합니다. 이 저장소의 포함 규칙은 단 한 줄이며, 그 한 줄이 이 모음집의 핵심입니다:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

2026년 8월 기준으로 이 저장소에는 Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel, VoltAgent 등 7개의 파일이 나열되어 있습니다. 각 파일은 고정된 공개 URL에 위치하므로 지금 바로 터미널에서 읽어볼 수 있습니다.

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

이 두 파일은 모두 디자인 시스템 문서입니다. 이 문서들은 제품이 어떤 모습이어야 하는지(색상, 서체, 간격, 움직임)를 설명합니다. 주제 자체보다는 글의 형태가 더 유용하므로 그 부분을 중점적으로 읽어보시기 바랍니다.

Nuxt 파일은 약 2,100단어 분량이며, 대부분은 이유가 명시된 규칙으로 구성되어 있습니다:

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

Vercel 파일은 2026년 8월 기준 약 6,500단어로 더 길며, 한 단계 더 나아갑니다. 해당 파일의 헤딩 중 하나는 Reject generated-design reflexes입니다. 그 아래에는 아무런 지시가 없을 때 유능한 생성기가 기본적으로 선택하는 항목들의 목록이 있습니다:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

이 문장이 파일의 유형을 정의합니다. 이는 확신을 가진 모델이 생성하는 기본값들을 기록한 목록이며, 모델이 더 이상 그러한 기본값을 생성하지 않도록 하기 위해 공개된 것입니다. 커밋할 가치가 있는 모든 DESIGN.md 파일은 특정 도메인에 대한 바로 그러한 목록입니다.

기업들은 왜 자체적인 DESIGN.md를 공개하는가?

커뮤니티가 먼저 시작했습니다. awesome-design-md에는 공개된 웹사이트를 리버스 엔지니어링하여 추출한 73개의 파일이 저장되어 있습니다. 각 파일은 동일한 9개 섹션 형식으로 작성되어 있어, 에이전트가 이를 참조하면 해당 디자인과 유사한 결과물을 생성할 수 있습니다. 이 파일들은 유용하지만 여전히 추측에 기반합니다. 해당 기업의 누구도 이를 검토하지 않았기 때문입니다.

직접 작성한 파일(first-party file)은 결과물을 해석한 것이 아니라 원본이라는 점에서 다릅니다. Vercel이 타이포그래피 스케일을 변경하면 vercel.com/design.md도 함께 변경됩니다. 3월에 긁어온 복사본은 에이전트에게 계속해서 예전 스케일을 학습시키며, 저장소 내의 그 무엇도 해당 복사본이 구식이 되었다는 사실을 알려주지 않습니다.

7개의 발행사는 적은 숫자이며, 저장소에서도 이를 명시하고 있습니다. 표준은 아직 초기 단계이며 공식적인 채택은 증가하는 추세입니다. 두 컬렉션 모두 자체 파일을 발행하는 오픈 소스 에이전트 프레임워크인 VoltAgent가 관리하므로, 이 목록을 중립적인 전수 조사가 아닌 추적 도구로 보아야 합니다. 그럼에도 불구하고 7개 기업의 면면을 고려할 때 주목할 가치는 충분합니다. 이들은 다른 개발자들이 프론트엔드 코드를 가장 많이 복사하는 기업들이며, 이들의 파일은 DESIGN.md가 무엇인지 보여주는 모범 사례가 되고 있습니다. AGENTS.md가 걸어온 경로를 비교해 보십시오. agents.md는 현재 60,000개 이상의 오픈 소스 프로젝트가 해당 형식을 사용하고 있으며, 관리 주체는 Linux Foundation 산하의 Agentic AI Foundation입니다. 에이전트가 읽을 수 있는 파일에 대한 관례는 빠르게 정착되고 있으며, 이는 상위권 기업들로부터 시작되고 있습니다.

사용자 인터페이스가 없는 프로젝트의 DESIGN.md 작성법

VPS에서 실행되는 대부분의 소프트웨어는 정의할 시각적 언어가 없습니다. 그럼에도 이 파일은 여전히 존재 가치가 있습니다. 메커니즘은 색상과는 아무런 관련이 없기 때문입니다. 이 파일은 숙련된 편집자라도 인지하지 못한 채 위반할 수 있는 제약 사항을 기록하는 용도입니다.

불변량(Invariants). 각 문장은 편집 후에도 반드시 유지되어야 하는 사실을 한 문장으로 기술합니다. "모든 쓰기 작업은 queue.enqueue()를 거쳐야 합니다. 데이터베이스에 직접 쓰면 감사 로그가 누락되며, 규정 준수 내보내기 기능은 이 감사 로그를 읽기 때문입니다." 이유가 포함된 불변량은 예상치 못한 작업 상황에서도 유지됩니다. 이유 없는 불변량은 단순한 선호 사항으로 읽히며, 선호 사항은 최적화 과정에서 제거되기 쉽습니다.

기각된 대안(Rejected alternatives). 명백한 선택지와 그것이 기각된 이유입니다. "캐싱을 위해 Redis를 사용하지 않습니다. 서비스가 단일 VPS에서 실행되므로 인프로세스 맵이 더 빠르며, 유지해야 할 데몬이 하나 줄어듭니다. 두 번째 애플리케이션 서버가 생기면 이 결정을 재검토합니다." 이 단락이 없다면 캐시 속도 향상을 요청받은 담당자는 Redis를 추가할 것이며, 이는 올바른 판단입니다. 제약 사항을 전달하지 않았기 때문입니다. 이 섹션이 파일 전체의 가치를 증명합니다.

경계(Boundaries). 작은 수정이 큰 파급 효과를 일으키는 지점입니다. 데이터베이스 스키마, 고객이 이미 스크립트로 사용 중인 공개 경로 접두사, 애플리케이션 시작 전 배포 과정에서 읽는 설정 파일, 단일 인스턴스 실행을 전제로 하는 cron 항목 등이 해당합니다. 이러한 항목을 명시하고, 각 항목을 변경할 때 발생하는 비용을 기술하십시오.

어휘(Vocabulary). 코드에서는 tenant이라고 부르는데 팀에서는 customer이라고 부른다면, 그 대응 관계를 기록하십시오. 여기서 잘못 추측한 담당자는 코드는 매끄럽게 읽히지만 실제 모델과는 다른 코드를 작성하게 됩니다. 이는 코드 리뷰에서 가장 발견하기 어려운 유형의 실수입니다.

오늘 바로 복사해서 사용할 수 있는 DESIGN.md

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

기억나는 대로 작성할 수 있는 두 섹션인 불변성(invariants)과 기각된 대안(rejected alternatives)을 채우고, 나머지는 제목으로 남겨 두십시오. 정직하게 작성된 네 줄짜리 파일이 낫습니다. 추측으로 채운 마흔 줄짜리 파일은 도움이 되지 않습니다.

일부 도구는 저장소 루트의 모든 마크다운 파일을 불러오지만, 일부는 지정된 파일만 불러오므로 이를 가정하지 마십시오. AGENTS.md를 가리키는 포인터를 추가하십시오:

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

안티패턴: README를 반복하는 DESIGN.md

가장 흔한 나쁜 사례는 읽기는 좋지만 아무것도 가르쳐주지 않는 문서입니다. 이 문서는 프로젝트의 기능 설명으로 시작하여, 특징을 나열하고, 설치 방법을 설명한 뒤 라이선스로 끝을 맺습니다. 이 모든 내용은 이미 README에 포함되어 있으며, 왜 그렇게 설계되었는지에 대한 이유는 전혀 담겨 있지 않습니다.

이로 인해 두 가지 비용이 발생합니다. 첫 번째는 컨텍스트 비용입니다. 에이전트가 모든 작업 시작 시 읽어 들이는 파일은 작업마다 비용을 지불하는 셈이며, 중복된 설치 섹션은 고정된 컨텍스트 윈도우에서 순수한 오버헤드가 됩니다. 이 윈도우를 관리하는 것은 그 자체로 하나의 기술이며, Claude Code에서 컨텍스트 윈도우 관리하기에서 다룹니다. 요약하자면, 자동으로 로드되는 모든 텍스트는 저장소에서 가장 가치 있는 내용이어야 합니다.

두 번째 비용은 더 치명적입니다. 동일한 내용의 두 복사본은 시간이 지나면서 서로 달라집니다. README에는 서비스가 8080 포트에서 대기한다고 되어 있는데 DESIGN.md에는 여전히 3000으로 적혀 있다면, 에이전트는 어느 쪽이 옳은지 판단할 방법이 없어 하나를 선택하고 그에 맞춰 코드를 작성하게 됩니다. 때때로 틀린 정보를 담고 있는 파일은 항상 옳은 파일과 동일한 신뢰도로 참조됩니다.

판단 기준은 간단합니다. 만약 어떤 문단이 README에 들어가도 어색하지 않다면, DESIGN.md에서 삭제하십시오. 남은 내용은 코드 리뷰에서 소리 내어 말할 법한 부분, 즉 "그건 이미 시도해 보았습니다"로 시작하는 내용이어야 합니다.

파일이 제대로 작동하는지 확인하는 방법

이 파일에 대한 린터(linter)는 없습니다. 1분 안에 실행할 수 있는 확인 방법이 있습니다.

에이전트에게 불변성(invariant)을 직접 건드리는 작업을 부여하십시오. "오래된 행을 만료됨으로 표시하는 백업 작업을 추가하라"와 같은 작업입니다. 제대로 작동하는 파일이라면 코드를 작성하기 전에 답변에서 그 내용이 드러나야 합니다. 에이전트는 해당 작업이 queue.enqueue()를 통해 기록되어야 한다고 말해야 합니다. 직접 쓰기(direct write)를 수행하면 감사 로그(audit log)를 건너뛰게 되기 때문입니다. 만약 에이전트가 데이터베이스 연결을 열고 직접 쓰기를 수행한다면, 다음 두 가지 중 하나입니다. 파일이 전혀 읽히지 않고 있거나, 불변성 정의가 논쟁의 여지가 있을 만큼 느슨하게 작성된 것입니다.

토큰 사용량도 확인하십시오. 이 파일은 매 턴마다 로드됩니다. DESIGN.md를 추가한 후 컨텍스트 사용량이 급증했는데 답변의 품질은 나아지지 않는다면, 해당 파일에는 에이전트가 이미 알고 있는 산문이 포함되어 있는 것입니다. Claude Code에서 토큰 카운터 읽기를 통해 예산이 어디에 사용되는지 확인할 수 있습니다.

이 점은 에이전트가 노트북이 아닌 서버에서 실행될 때 가장 중요합니다. tmux를 사용하는 VPS의 Claude Code 워크스페이스와 같이 장시간 실행되는 세션에서 작업하는 에이전트는 어제의 대화 내용을 기억하지 못합니다. 저장소(repository)가 곧 기억입니다. 채팅에서 설명했지만 커밋하지 않은 모든 내용은 다음 세션이 되면 사라집니다. DESIGN.md는 그러한 설명이 살아남을 수 있도록 기록하는 곳입니다.

논쟁이 되는 결정부터 시작하기

첫 번째 버전은 20분이면 완성됩니다. 리뷰어가 "아니요, 여기서는 다르게 처리합니다"라고 작성한 최근의 pull request들을 열어보십시오. 이러한 코멘트 하나하나는 문서화되지 않은 불변의 규칙이며, 에이전트가 사람보다 더 빠르고 빈번하게 동일한 실수를 저지를 지점입니다. 정해진 일정에 따르지 말고, 에이전트가 실패할 때마다 해당 파일에 내용을 추가하십시오. 일반적인 개발 워크플로우에 에이전트를 어떻게 도입할지 고민 중이라면, 2026년형 AI 에이전트 학습 가이드가 적절한 다음 단계가 될 것입니다.

FAQ

DESIGN.md는 공식 표준입니까?

AGENTS.md와 같은 방식의 공식 표준은 아닙니다. AGENTS.md는 agents.md라는 공식 홈페이지가 있고, 60,000개 이상의 오픈 소스 프로젝트에서 사용하며, Linux Foundation 산하의 Agentic AI Foundation에서 관리합니다. 2026년 8월 기준으로 DESIGN.md는 관리 주체가 없으며 공개된 명세도 없습니다. 대신 Vercel, Nuxt, Atlassian, Resend를 포함한 7개 기업이 공개 URL에 게시하고 있으며, 커뮤니티 컬렉션에는 공개 사이트에서 역공학으로 추출한 73개의 사례가 있습니다. 섹션 이름을 검증할 표준이 없으므로, 지금 바로 도입하여 자유롭게 확장할 수 있는 관례로 취급하십시오.

DESIGN.md를 AGENTS.md의 한 섹션으로 두어야 합니까?

소규모 저장소라면 그렇습니다. 에이전트가 확실히 읽는 파일 하나가 무시될 가능성이 있는 파일 두 개보다 낫습니다. AGENTS.md를 훑어보기 어려워지거나, 두 파일의 변경 주기가 다르다고 느껴질 때 분리하십시오. AGENTS.md는 빌드 환경이 바뀔 때 변경됩니다. DESIGN.md는 의사결정이 바뀔 때 변경되는데, 이는 더 드물고 더 중요한 사안입니다. 분리할 때는 AGENTS.md에 에이전트가 코드를 수정하기 전에 DESIGN.md를 읽도록 지시하는 한 줄을 추가하십시오. 모든 도구가 루트 디렉터리의 모든 마크다운 파일을 불러오는 것은 아니기 때문입니다.

DESIGN.md는 아키텍처 결정 기록(ADR)과 어떻게 다릅니까?

ADR(architecture decision record)은 특정 시점의 결정 사항을 기록한 문서이며, 건전한 프로젝트는 폴더 하나에 수십 개의 ADR을 쌓아둡니다. 이는 과거의 기록이며, 에이전트가 무엇이 여전히 유효한지 파악하기 위해 모든 기록을 읽어야 하므로 불러오기 비용이 큽니다. DESIGN.md는 현재 상태를 담고 있으며, 모든 작업 시 전체를 읽도록 작성됩니다. 이미 ADR을 작성하고 있다면 둘 다 유지하십시오. ADR은 무엇이 언제 결정되었는지 말해주고, DESIGN.md는 오늘 무엇이 유효한지 말해주며 에이전트가 참조해야 할 대상입니다.

DESIGN.md의 길이는 어느 정도가 적당합니까?

매번 불러와도 부담이 없을 정도로 짧아야 합니다. 공개된 예시들이 긴 이유는 전체 시