DESIGN.md로 AI 에이전트에 설계 의도 알리기

DESIGN.md란 무엇이며 AGENTS.md에서 다루지 않는 내용

DESIGN.md는 저장소 루트에 두는 markdown 파일이다. 코드가 현재와 같은 구조를 갖게 된 이유를 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년 10월 기준으로 다음 11개가 등록되어 있습니다: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel, VoltAgent. 각 파일은 공개 URL에 있으며, 대부분은 게시자 자체 도메인에, 나머지는 공개 GitHub 저장소에 있습니다. 따라서 지금 바로 터미널에서 하나를 읽을 수 있습니다.

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

두 파일 모두 design system 문서입니다. 제품이 어떻게 보여야 하는지 설명합니다. 색상, 글꼴, 간격, 모션을 다룹니다. 주제 자체보다 글의 형태에 주목해야 합니다. 유용한 부분은 주제가 아니라 작성 방식이기 때문입니다.

Nuxt 파일은 2026년 10월 27일 기준으로 약 2,000단어에 이르며, 대부분의 내용은 이유가 함께 제시된 규칙입니다. 문서는 다크 모드가 기본 테마라고 명시하면서 시작합니다. 브랜드 그린 #00DC82을 제시하고, 브랜드 색상은 "로고, 소셜 이미지, 인쇄물에 사용합니다. UI 코드에서 원시 값으로 사용하지 마세요."라는 주석을 덧붙입니다. 끝부분에 가까운 곳에는 Reject these라는 제목의 섹션이 있으며, 다음 내용이 포함됩니다.

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

Vercel 파일은 2026년 10월 기준으로 약 6,000단어로 더 길며, 한 단계 더 나아갑니다. 제목 중 하나는 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에는 2026년 10월 27일 README에 표시된 집계 기준으로 공개 웹사이트에서 추출한 파일 84개가 있습니다. 각 파일은 동일한 9개 섹션 형식으로 작성되어 있으므로, 에이전트에 그중 하나를 지정하면 해당 디자인과 비슷한 결과를 만들 수 있습니다. 이러한 파일은 유용하지만 여전히 추정에 불과합니다. 해당 기업의 누구도 그 파일을 검토하지 않았습니다.

퍼스트파티 파일은 결과물을 해석한 내용이 아니라 원본이므로 다릅니다. Vercel이 타입 스케일을 변경하면 vercel.com/design.md도 함께 변경됩니다. 3월에 스크랩한 사본은 에이전트에 이전 스케일을 계속 학습시키며, 저장소의 어떤 정보도 그 사본이 오래되었다고 알려 주지 않습니다.

퍼블리셔 11곳은 여전히 적은 수이며, 저장소도 이를 명시합니다. 표준은 새로 만들어졌고 공식 도입은 늘고 있습니다. 두 컬렉션 모두 자체 파일도 공개하는 오픈 소스 에이전트 프레임워크인 VoltAgent가 관리하므로, 이 목록은 중립적인 전수 조사가 아니라 추적 목록으로 읽어야 합니다. 그래도 어떤 기업이 포함되어 있는지를 보면 계속 지켜볼 가치가 있습니다. 여러 기업이 다른 개발자들이 프런트엔드 코드를 가장 많이 복사하는 기업이며, 새로 추가된 Ant Design, Microsoft FAST, Juspay, Oxide Computer는 다른 팀이 기반으로 사용하는 디자인 시스템입니다. 이들의 파일은 DESIGN.md가 무엇인지 보여 주는 실제 사례가 되고 있습니다. AGENTS.md가 거쳐 온 경로와 비교해 보십시오. agents.md는 현재 이 형식을 사용하는 오픈 소스 프로젝트가 60,000개를 넘는다고 집계하며, 관리는 Linux Foundation 산하 Agentic AI Foundation이 맡고 있습니다. DESIGN.md도 같은 경로로 들어서기 시작했습니다. 2026년 4월 21일 Google은 이 형식의 초안 사양을 오픈 소스로 공개했으며, 토큰 스키마와 CLI를 Apache-2.0 licence로 google-labs-code/design.md에 게시했습니다. 2026년 10월 현재 이 형식은 alpha 버전이며 아직 활발히 개발되고 있습니다. 또한 중립적인 재단이 아니라 Google Labs가 관리하고, 시각적 정체성을 설명하므로 백엔드 파일에 필요한 불변 조건에 대해서는 아무것도 말하지 않습니다. 에이전트가 읽을 수 있는 파일의 규칙은 빠르게 정착하고 있으며, 그 방향은 상위 계층에서 정해지고 있습니다.

UI가 없는 프로젝트에서 DESIGN.md에는 무엇을 작성해야 하는가

VPS에서 실행되는 소프트웨어 대부분은 지정할 시각적 언어가 없다. 그래도 이 파일은 충분한 역할을 한다. 그 핵심은 색상이 아니기 때문이다. 자신 있는 편집자라면 알아차리지 못한 채 위반할 제약을 문서로 남기는 것이다.

불변 조건. 편집 후에도 반드시 유지되어야 하는 내용을 한 문장씩 작성한다. "모든 쓰기 작업은 queue.enqueue()을 거친다. 데이터베이스에 직접 쓰면 감사 로그를 건너뛰며, 컴플라이언스 내보내기는 감사 로그를 읽는다." 이유가 함께 있는 불변 조건은 예상하지 못한 작업을 마주해도 유지된다. 불변 조건만 단독으로 작성하면 선호 사항처럼 보이며, 선호 사항은 최적화 과정에서 제거된다.

거부한 대안. 당연해 보였던 선택지와 그것을 채택하지 않은 이유를 작성한다. "캐싱에 Redis를 사용하지 않는다. 서비스가 단일 VPS에서 실행되므로 프로세스 내 맵이 더 빠르고, 계속 실행해야 할 daemon도 하나 줄어든다. 두 번째 애플리케이션 서버가 생기면 이 결정을 재검토한다." 이 문단이 없으면 cache 성능 개선을 요청받은 agent가 Redis를 추가한다. 그렇게 하는 것이 맞다. 해당 제약을 알려주지 않았기 때문이다. 이 항목이 파일 전체의 작성 비용을 회수한다.

경계. 작은 편집이 큰 영향 범위를 만드는 지점을 작성한다. 데이터베이스 스키마. 고객이 이미 스크립트에서 사용하는 public route prefix. 애플리케이션이 시작하기 전에 deploy가 읽는 config file. 해당 작업이 한 번만 실행된다고 가정하는 cron entry. 이러한 항목의 이름을 적고, 각각을 변경할 때 발생하는 비용을 설명한다. agent가 검색 backend로 연결된 self-hosted SearXNG instance를 통해 open web에도 접근할 수 있다면, 이 역시 기록할 가치가 있는 경계다. 가져온 텍스트 중 어떤 내용이 code에 영향을 주도록 허용되는지, 어떤 내용은 사용자에게 그대로 인용해서 돌려주기만 하는지를 파일에 명시해야 하기 때문이다.

용어. code에서 tenant라고 하고 팀에서 customer이라고 한다면 그 대응 관계를 기록한다. 여기서 잘못 추측한 agent는 겉보기에는 자연스럽지만 잘못된 대상을 모델링하는 code를 만든다. 이런 실수는 review에서 발견하기 가장 어렵다.

오늘 바로 복사해 사용할 수 있는 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.

오늘 기억만으로 작성할 수 있는 두 섹션인 불변 조건과 거부한 대안을 채우고, 나머지는 제목만 남긴다. 정직하게 작성한 4줄짜리 파일은 문제가 없다. 추측으로 채운 40줄짜리 파일은 그렇지 않다. 저장소에 여러 패키지가 있다면 루트 파일 하나로 모두 다룰 수 없다. 이 경우 모노레포의 중첩된 AGENTS.md 파일에 적용한 것과 같은 디렉터리별 분할 방식을 사용한다. 모든 패키지가 공유하는 결정을 짧은 루트 파일에 기록하고, 고유한 결정이 있는 각 패키지 옆에는 더 작은 파일을 둔다.

일부 도구는 저장소 루트의 모든 markdown 파일을 로드하고, 일부 도구는 지정된 파일 하나만 로드한다. 따라서 이를 당연하게 가정하지 않는다. 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에 이미 있으며, 어느 항목도 왜 그렇게 설계했는지는 설명하지 않는다.

이렇게 하면 비용이 두 번 발생한다. 첫 번째 비용은 컨텍스트다. 모든 작업을 시작할 때마다 agent가 읽는 파일은 모든 작업에서 비용을 발생시키며, 중복된 설치 섹션은 제한된 컨텍스트 윈도우를 순수한 오버헤드로 소모한다. 이 윈도우를 할당하는 일 자체가 별도의 기술이며, Claude Code에서 컨텍스트 윈도우 관리에서 다룬다. 요점은 간단하다. 자동으로 로드되는 내용은 저장소에서 가치가 가장 높은 텍스트여야 한다.

두 번째 비용은 더 크다. 같은 문장을 두 곳에 두면 서로 다른 내용으로 변한다. README에는 서비스가 8080에서 수신 대기한다고 되어 있지만 DESIGN.md에는 여전히 3000이라고 적혀 있을 수 있다. agent는 어느 내용을 우선해야 하는지 판단할 방법이 없으므로 하나를 선택하고 그에 맞춰 코드를 작성한다. 때때로 틀리는 파일도 항상 옳은 파일과 같은 신뢰도로 참조된다.

확인 방법은 간단하다. 어떤 단락이 README에 자연스럽게 들어갈 수 있다면 DESIGN.md에서 삭제한다. 남아야 하는 내용은 코드 리뷰에서 직접 말할 부분, 즉 “이미 그렇게 해 봤다”로 시작하는 부분이다.

파일이 제대로 작동하는지 어떻게 확인합니까?

이를 위한 linter는 없습니다. 1분 안에 실행할 수 있는 확인 방법이 있습니다.

불변 조건을 바로 위반하는 작업을 agent에 할당합니다. “stale row를 expired로 표시하는 background job을 추가하십시오.” 파일이 제 역할을 한다면 어떤 코드보다 먼저 응답에 드러납니다. agent는 직접 쓰기를 수행하면 audit log를 건너뛰므로 작업이 queue.enqueue()를 통해 기록된다고 말해야 합니다. agent가 database connection을 열고 직접 쓴다면 두 가지 중 하나입니다. 파일을 전혀 읽지 않았거나, 불변 조건이 논쟁의 여지가 있을 정도로 모호하게 작성된 것입니다.

token count도 확인해야 합니다. 이 파일은 모든 turn에서 로드되기 때문입니다. DESIGN.md를 추가한 뒤 context 사용량이 증가했는데 답변이 더 좋아지지 않는다면, agent가 이미 알고 있던 내용을 파일이 장황하게 반복하고 있는 것입니다. Claude Code에서 token counter 읽기에서 해당 budget이 어디에 사용되는지 확인할 수 있습니다.

agent가 노트북이 아니라 server에서 실행될 때 특히 중요합니다. tmux를 사용한 VPS의 Claude Code workspace와 같이 장시간 실행되는 session에서 작업하는 agent는 어제 대화를 기억하지 못합니다. repository가 memory 역할을 합니다. chat에서 설명했지만 commit하지 않은 내용은 다음 session이 시작되면 사라집니다. DESIGN.md에 그 설명을 기록해야 다음 session에도 유지됩니다.

논쟁이 있었던 결정부터 시작한다

첫 번째 버전은 20분이면 작성할 수 있다. 검토자가 "아니요, 여기서는 다르게 합니다"라고 작성한 최근 pull request 몇 개를 연다. 이러한 댓글은 문서로 작성되지 않았던 불변 조건이며, 각각 에이전트가 사람이 같은 실수를 하는 것보다 더 빠르고 더 자주 반복할 지점이다. 일정에 따라 파일을 업데이트하지 말고, 파일이 문제를 일으킬 때 업데이트한다. 일반적인 개발 워크플로에서 에이전트를 어떻게 활용할지 아직 정리하는 중이라면 2026년 AI 에이전트 학습 가이드를 다음에 참고할 만하다.

FAQ

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

AGENTS.md와 같은 의미의 공식 표준은 아닙니다. AGENTS.md는 agents.md에 공식 사이트가 있고, 60,000개가 넘는 오픈 소스 프로젝트에서 사용되며, Linux Foundation 산하 Agentic AI Foundation이 관리합니다. DESIGN.md에는 공개된 사양이 있지만 중립적인 관리 주체는 없습니다. Google은 2026년 4월 21일에 초안 사양을 오픈 소스로 공개했으며, 이 사양은 Apache-2.0 라이선스의 google-labs-code/design.md 저장소에 있습니다. 2026년 10월 기준으로 alpha 버전이며 여전히 개발 중입니다. 색상, 타이포그래피, 레이아웃, 컴포넌트 등 시각적 정체성을 설명합니다. DESIGN.md는 실제 채택 사례도 있습니다. Vercel, Nuxt, Atlassian, Resend를 포함한 11개 회사와 프로젝트가 DESIGN.md를 공개하고 있으며, 커뮤니티 모음에는 2026년 10월 27일 기준 공개 사이트에서 추출한 항목이 84개 더 있습니다. 백엔드의 불변 조건과 거부한 대안을 기록하는 파일로 사용하려면, 지금 채택하고 자유롭게 확장할 수 있는 관례로 취급해야 합니다. 이러한 섹션 이름을 다루는 사양은 없기 때문입니다.

DESIGN.md를 AGENTS.md의 한 섹션으로만 작성해야 합니까?

작은 저장소라면 그렇습니다. 에이전트가 반드시 읽는 파일 1개가 읽지 않을 수 있는 파일 2개보다 낫습니다. AGENTS.md를 한눈에 검토하기 어려워지거나 두 부분이 서로 다른 속도로 변경되는 것을 확인하면 파일을 분리합니다. 빌드가 변경되면 AGENTS.md가 변경됩니다. 결정이 변경되면 DESIGN.md가 변경됩니다. 후자는 더 드물게 발생하며 더 큰 의미를 가집니다. 분리할 때는 코드 편집 전에 DESIGN.md를 읽으라고 AGENTS.md에 한 줄을 추가해야 합니다. 모든 도구가 루트의 모든 markdown 파일을 읽는 것은 아니기 때문입니다.

DESIGN.md는 architecture decision record와 어떻게 다릅니까?

ADR(architecture decision record)은 하나의 결정을 날짜와 함께 기록한 문서이며, 정상적으로 운영되는 프로젝트에는 이러한 문서가 폴더에 수십 개씩 쌓입니다. 이것은 기록입니다. 에이전트가 현재도 유효한 결정을 파악하려면 모든 문서를 읽어야 하므로 기록을 불러오는 데는 비용이 큽니다. DESIGN.md는 현재 상태를 기록하며, 모든 작업에서 전체를 읽도록 작성합니다. 이미 ADR을 작성하고 있다면 두 가지를 모두 유지합니다. ADR에는 무엇을 언제 결정했는지가 기록됩니다. DESIGN.md에는 현재 사실인 내용이 기록되며, 에이전트에게 안내할 문서는 DESIGN.md입니다.

DESIGN.md는 어느 정도 길이로 작성해야 합니까?

매번 불러와도 후회하지 않을 정도로 짧아야 합니다. 공개된 예시는 전체 시각 언어를 정의하므로 깁니다. 2026년 10월 기준으로 Nuxt 파일은 대략 2,000단어이고 Vercel 파일은 대략 6,000단어입니다. 백엔드 서비스에는 일반적으로 훨씬 적은 내용만 필요합니다. 한 페이지로 시작하고, 한 문장으로 예방할 수 있었던 오류를 에이전트가 실제로 일으켰을 때만 내용을 늘립니다. 길이는 기준이 아닙니다. 각 줄은 에이전트가 그렇지 않았다면 잘못 처리했을 내용이어야 합니다.