DESIGN.md 작성법: AI 에이전트의 코드 수정을 방지하는 법

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

DESIGN.md는 저장소 루트에 위치한 마크다운 파일로, AI 코딩 에이전트에게 코드의 구조가 왜 현재와 같은지 그 이유를 설명합니다. AGENTS.md는 이와 다른 질문, 즉 '이곳에서 어떻게 작업하는가'에 답합니다. 여기에는 빌드 명령어, 테스트 명령어, 통과해야 하는 린트(lint) 규칙, 그리고 수정해서는 안 되는 경로 등이 포함됩니다. 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) 파일은 결과물을 해석한 것이 아니라 원본 그 자체라는 점에서 다릅니다. 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 항목 등이 해당합니다. 각 항목을 명시하고 변경 시 발생하는 비용을 기술하십시오. 에이전트가 외부 웹에 접근할 수 있다면, 검색 백엔드로 연결된 자체 호스팅 SearXNG 인스턴스와 같은 경로도 경계로서 기록할 가치가 있습니다. 어떤 외부 텍스트가 코드 로직에 영향을 줄 수 있고, 어떤 텍스트가 단순히 사용자에게 인용만 되는지 명확히 해야 하기 때문입니다.

어휘(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 파일에서 사용하는 디렉터리별 분할 방식이 여기에도 적용됩니다. 모든 구성 요소가 공유하는 결정 사항은 짧은 루트 파일에 담고, 각 패키지별로 고유한 결정 사항은 해당 패키지 옆에 더 작은 파일을 두십시오.

일부 도구는 저장소 루트의 모든 마크다운 파일을 불러오지만, 일부는 지정된 파일만 불러오므로 가정하지 마십시오. 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()를 통해 기록되어야 한다고 말해야 합니다. 직접 쓰기를 수행하면 감사 로그(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입니다.

DESIGN.md는 어느 정도 길이어야 합니까?

매번 로드해도 부담이 없을 정도로 짧아야 합니다. 공개된 예시들이 긴 이유는 전체 시각 언어를 명시하기 때문입니다. 2026년 8월 기준으로 Nuxt 파일은 약 2,100단어, Vercel 파일은 약 6,500단어입니다. 백엔드 서비스는 보통 이보다 훨씬 적은 분량으로 충분합니다. 한 페이지로 시작하고, 문장 한 줄로 방지할 수 있었던 실수를 에이전트가 반복할 때만 내용을 추가하십시오. 길이는 중요하지 않습니다. 모든 줄은 에이전트가 잘못 이해할 가능성이 있는 내용이어야 합니다.