Blog

코딩 에이전트 DESIGN.md란?

Ashley Innocent

Ashley Innocent

21 May 2026

코딩 에이전트 DESIGN.md란?

코딩 에이전트는 자신감 있고 빠르지만, 지시하지 않으면 코드베이스의 아키텍처를 전혀 모릅니다. Claude Code나 Codex에 모호한 티켓을 넘기면, 컴파일되고 간단한 테스트를 통과하며 도메인 계층과 HTTP 계층 사이의 경계를 조용히 위반하는 코드를 기꺼이 작성할 것입니다. 에이전트는 설계 문서를 읽지 않았습니다. 에이전트가 볼 수 있는 파일을 읽고, 패턴을 매칭하고, 추측한 것입니다. `DESIGN.md` 파일은 에이전트가 항상 살펴보는 유일한 장소, 즉 저장소 자체에 아키텍처 의도를 기록함으로써 추측 문제를 해결합니다.

요약

`DESIGN.md`는 코드베이스의 아키텍처 의도, 제약 조건 및 설계 결정을 일반 Markdown으로 기록하는 커뮤니티 관례 저장소 파일입니다. 이를 통해 코딩 에이전트(Claude Code, Codex, Cursor)는 시스템과 충돌하는 대신 시스템에 맞는 코드를 생성합니다. `AGENTS.md`가 "어떻게 빌드하고 테스트하는가"에 답한다면, `DESIGN.md`는 "코드가 왜 이런 방식으로 구성되어 있는가"에 답합니다.

버튼

소개

코딩 에이전트를 도입하는 모든 팀이 일주일 안에 겪게 될 실패 모드는 다음과 같습니다. 에이전트에게 결제 서비스에 환불 엔드포인트를 추가해달라고 요청합니다. 그러면 에이전트는 컨트롤러에서 데이터베이스를 직접 호출하고, 게이트웨이 오류를 삼키며, 이미 존재하는 돈 유형을 알아차리지 못해 새로운 돈 유형을 발명하는 작동하는 핸들러를 반환합니다. 차이점은 깔끔합니다. 테스트도 통과합니다. 하지만 아키텍처를 아는 검토자만이 잡아낼 수 있는 세 가지 방식으로 잘못되었습니다. 에이전트가 코딩을 못하는 것이 아니라, 당신의 머릿속, Notion 페이지, 또는 8개월 전 슬랙 스레드에 있는 결정 사항들을 보지 못하는 것입니다.

`DESIGN.md`는 점점 더 많은 팀이 채택하고 있는 해답입니다. 이는 저장소 루트에 커밋되는 단일 Markdown 파일로, 에이전트에게 시스템에 대한 중요한 사실들을 알려줍니다: 계층화 규칙, 절대 깨져서는 안 되는 불변 조건, 의도적으로 선택한 패턴, 그리고 거부한 패턴들입니다. 이것은 벤더 사양이 아니고 소유하는 위원회도 없습니다. `ARCHITECTURE.md`와 `CONTRIBUTING.md`가 관례인 것처럼, `DESIGN.md`도 관례입니다. 하지만 에이전트가 이미 읽고 있는 도구별 지침 파일과 자연스럽게 연결되며, API 및 백엔드 작업에 있어서 작성할 수 있는 가장 영향력 있는 문서 중 하나입니다.

DESIGN.md는 실제로 무엇인가

`DESIGN.md`는 *코드가 현재와 같은 모습을 가지는 이유*를 기록한 일반 텍스트 파일입니다. 코드가 무엇을 하는지(그것은 README), 어떻게 실행하는지(그것은 `AGENTS.md`)가 아니라, 선임 엔지니어가 신입 사원에게 중요한 것을 건드리기 전에 첫날 설명해 줄 법한 이유를 담고 있습니다.

어떤 파일에도 없는 대화들을 생각해 보세요. "요청 스레드에서 결제 게이트웨이를 호출하지 않습니다. 게이트웨이가 부하 시 타임아웃되기 때문에 모든 것은 아웃박스 테이블을 통해 처리됩니다." "금액은 항상 최소 단위의 정수(센트)로 계산됩니다. 반올림 사고 이후 부동 소수점 사용을 금지했습니다." "`Account` 애그리게이트가 잔액 변경을 소유합니다. 다른 어떤 것도 원장에 쓰지 않습니다." 이것들은 설계 결정입니다. 에이전트가 소스 코드를 읽을 때는 보이지 않습니다. 소스 코드는 결정의 *결과*를 보여줄 뿐, 결정 자체나 그 근거를 보여주지는 않기 때문입니다. 에이전트는 `Account.debit()`가 존재한다는 것을 볼 수 있습니다. 하지만 그것을 의도적으로 유일한 쓰기 경로로 만들었다는 사실은 볼 수 없으므로, 기꺼이 두 번째 쓰기 경로를 추가할 것입니다.

이 관례는 오래되고 잘 정립된 관행에 뿌리를 두고 있습니다. `ARCHITECTURE.md` 패턴(Alex Kladov의 널리 인용된 글에 의해 대중화됨)은 저장소가 코드와 줄 단위로 동기화를 유지하려고 노력하지 않고 구조와 불변 조건을 설명하는 코드베이스의 고수준 지도를 포함해야 한다고 주장합니다. 아키텍처 결정 기록(ADRs)은 시간이 지남에 따라 개별 결정과 그 근거를 기록합니다. `DESIGN.md`는 *코딩 에이전트를 포함한 독자를 위해* 그런 종류의 문서를 작성할 때 얻게 되는 것입니다: 간결하고, 선언적이며, 결정 중심적이고, 에이전트가 실제로 로드할 수 있는 위치에 놓여 있습니다.

두 가지 속성이 효과를 발휘하게 합니다. 저장소에 있으므로 에이전트는 코드를 읽는 것과 동일한 도구로 읽습니다. 플러그인이나 API 호출이 필요 없습니다. 그리고 의도에 관한 것이므로 파일이 이동하더라도 유용하게 유지됩니다. 패키지 이름을 바꾸면 README 스크린샷은 쓸모없게 되지만, "도메인 로직은 웹 프레임워크를 절대 임포트하지 않는다"는 규칙은 여전히 유효합니다.

DESIGN.md vs AGENTS.md vs CLAUDE.md vs README

이 파일들은 사람들을 혼란스럽게 할 만큼 충분히 겹치지만, 하나로 합치는 것이 실수일 만큼 충분히 다릅니다. 간략히 말해: `README`는 인간의 온보딩을 위한 것이고, `AGENTS.md`는 에이전트의 운영 계약이며, `CLAUDE.md`는 Claude 전용 지침 파일이고, `DESIGN.md`는 이들 모두에게 도움이 되는 아키텍처적 근거입니다.

`AGENTS.md`는 이제 실제로 널리 채택된 형식입니다. agents.md 프로젝트는 이를 "코딩 에이전트를 안내하기 위한 간단하고 개방적인 형식"이라고 설명하며, 수만 개의 프로젝트에서 사용되고 Linux Foundation의 Agentic AI Foundation에서 관리됩니다. 그 역할은 운영적입니다: 빌드 단계, 테스트 명령, 코드 스타일, 커밋 규칙 등 새로운 팀원에게 막히지 않도록 알려줄 내용들입니다. Anthropic의 Claude Code 메모리 문서에 따르면, `CLAUDE.md`는 Claude에 특화된 동일한 지침 역할을 합니다. 문서에서는 이미 `AGENTS.md`가 있는 경우, `@AGENTS.md`를 사용하여 `CLAUDE.md`를 생성하고 이를 임포트하여 두 도구가 단일 진실의 원천을 읽도록 권장하기도 합니다.

이러한 설명에서 빠진 점은 심층적인 아키텍처적 근거입니다. `AGENTS.md`와 `CLAUDE.md`는 짧게 유지되도록 조정됩니다. Claude Code 문서는 `CLAUDE.md`를 200줄 미만으로 유지하도록 명시적으로 권장하는데, 이는 파일이 길어질수록 컨텍스트를 소모하고 모델이 이를 따르는 신뢰도가 떨어지기 때문입니다. 실제 아키텍처 설명, 경계, 불변 조건, 거부된 대안, 데이터 모델 규칙 등은 파일을 부풀리지 않고는 거기에 들어맞지 않습니다. 따라서 대신 참조하는 것입니다. `DESIGN.md`는 심층 문서가 되고, `AGENTS.md` / `CLAUDE.md`는 한 줄로 이를 가리킵니다.

파일 대상 답변 수명 / 변경 빈도 길이
README.md 인간 (사용자, 신규 기여자) 이것은 무엇이며, 어떻게 시작하는가 기능과 함께 변경 중간
AGENTS.md 모든 코딩 에이전트 여기에서 어떻게 빌드하고, 테스트하고, 린트하고, 커밋하는가 도구와 함께 변경 짧음 (운영용)
CLAUDE.md 특히 Claude Code AGENTS.md와 동일, Claude 전용 규칙 추가 도구와 함께 변경 짧음 (~200줄 미만)
DESIGN.md 에이전트 + 엔지니어 + 검토자 시스템이 왜 이런 방식으로 구성되어 있는가; 절대 깨져서는 안 되는 것은 무엇인가 아키텍처와 함께 변경 (드묾) 중간, 결정 밀집

관계는 보완적이지 경쟁적이지 않습니다. Claude + Codex 환경의 깔끔한 설정은 다음과 같습니다: 인간을 위한 `README.md`; 빌드/테스트/스타일이 포함된 하나의 `AGENTS.md`; `@AGENTS.md`와 두 줄의 Claude 전용 라인만으로 구성된 `CLAUDE.md`; 그리고 아키텍처를 담고 있는 `DESIGN.md`는 `AGENTS.md`에서 링크되어 모든 에이전트가 필요할 때 로드하도록 합니다. 중복 없이 각 파일은 하나의 역할만 수행합니다. 이 파일들을 통해 Claude의 컨텍스트를 구조화하는 방법을 더 깊이 알고 싶다면, Claude Code 워크플로우에서 실제로 메모리 모델을 설명합니다.

DESIGN.md에 무엇을 넣을 것인가 (템플릿 포함)

`DESIGN.md`는 에이전트가 코드에서 추론할 수 없는 질문에 답해야 합니다: 시스템의 형태, 어떤 단일 파일에도 나타나지 않는 규칙, 그리고 의도적으로 내린 결정들입니다. 선언적으로 작성하세요. 모든 섹션은 에세이처럼 읽히는 것이 아니라, 검토자가 강제할 규칙처럼 읽혀야 합니다.

다음 사항들을 다루세요:

다음은 실제 결제 API 서비스를 위해 작성된 전체 템플릿입니다. 복사하여 해당하지 않는 부분을 삭제하고 나머지를 채워 넣으세요.

# DESIGN.md: 결제 API 서비스

이 파일은 아키텍처 의도와 그 이면의 결정을 기록합니다.
코드를 생성하거나 수정하기 전에 이 파일을 읽으세요. 변경 사항이
여기 규칙과 충돌하면, 우회하지 말고 중단하고 플래그를 지정하세요.

## 시스템 형태

계층형이며, 의존성은 안쪽으로만 향합니다:

  http (핸들러, DTO)  ->  app (유스케이스)  ->  domain (엔티티,
  불변 조건)  <-  infra (DB, 게이트웨이 클라이언트)

- `domain/`은 `http/`, `app/`, 또는 어떤 프레임워크로부터도 임포트가 없습니다.
- `infra/`는 `domain/` 또는 `app/`에 선언된 인터페이스를 구현합니다.
- `http/`는 데이터베이스나 결제 게이트웨이에 직접 접근하지 않습니다.
  `app/`의 유스케이스를 호출합니다.

## 불변 조건 (항상 유지되어야 함)

- 원장 항목은 일단 작성되면 불변합니다. 수정은 새로운
  상쇄 항목으로 이루어지며, 업데이트나 삭제는 절대 없습니다.
- 계정 잔액은 원장 항목에서 파생되며, 코드가 직접 설정할 수 있는
  가변 필드로 저장되지 않습니다.
- 금액은 최소 단위(센트)의 정수와 ISO-4217 통화 코드로 구성됩니다.
  절대 부동 소수점이 아닙니다. 한 작업에서 여러 통화를 혼합하지 마십시오.
- 외부 결제 게이트웨이에 대한 모든 호출은 `idempotency_key`에 의해
  멱등합니다. 재시도는 이중 청구를 유발해서는 안 됩니다.
- 명시적인 `OverdraftPolicy`가 해당 계정에 대해 승인하지 않는 한
  잔액이 마이너스가 되는 일은 없습니다.

## 주요 결정 및 근거

- **게이트웨이 호출을 위한 아웃박스 패턴.** 핸들러는 비즈니스 변경과
  동일한 DB 트랜잭션 내에서 의도(intent) 행을 작성한 다음,
  워커가 게이트웨이를 호출합니다. 근거: 게이트웨이가 부하 시 타임아웃됩니다.
  이를 인라인으로 처리하면 요청 지연 시간과 실패 처리가 소유자 불명이 됩니다.
  요청 핸들러에서 게이트웨이를 호출하지 마십시오.
- **애그리게이트당 단일 쓰기 경로.** `Account.post_entry()`만이
  원장에 기록합니다. 근거: 두 번째 쓰기 경로가 2025년 3월 잔액 불일치를
  야기했습니다. 새로운 동작은 새로운 쿼리가 아닌,
  애그리게이트의 메서드로 추가하십시오.
- **원장에 대해서만 이벤트 소싱.** 시스템의 나머지는 CRUD입니다.
  근거: 돈에 대한 완벽한 감사 추적이 필요하며 다른 것은 필요하지 않습니다.
  전체 이벤트 소싱은 다른 곳에서는 너무 비용이 많이 들었습니다.

## 거부된 대안 (다시 도입하지 마시오)

- 애그리게이트 전반에 걸친 ORM 지연 로딩; N+1 문제와 불분명한
  트랜잭션 경계를 야기했습니다. 리포지토리는 완전히 로드된 애그리게이트를 반환합니다.
- 잔액을 제자리에서 업데이트되는 컬럼으로 저장하는 방식; 잔액 불일치
  사고를 참조하십시오. 잔액은 항상 파생됩니다.
- 레지스트리에서 가져온 일반 `Money` 라이브러리; 우리는
  `domain/money.py`를 가지고 있습니다. 이것을 사용하십시오.
- 요청 스레드에서 상인에게 동기 웹훅을 호출하는 방식; 이것은
  블록되고 조용히 실패합니다. 알림 큐를 사용하십시오.

## 데이터 및 도메인 규칙

- 모든 타임스탬프는 UTC이며, timestamptz로 저장되고,
  가장자리에서 RFC 3339 형식으로 지정됩니다.
  함수 경계를 넘는 순수(naive) datetime은 없습니다.
- ID는 앱 계층에서 생성된 ULID이며, DB 자동 증가가 아닙니다.
- 소프트 삭제는 사용되지 않습니다. 레코드는 활성 상태이거나
  명시적인 유스케이스에 의해 아카이브 테이블로 이동됩니다.
- 멀티테넌트: 모든 쿼리는 `tenant_id`로 범위가 지정됩니다.
  테넌트 범위가 없는 리포지토리 메서드는 버그입니다.

## API 계약의 단일 진실 원천

- `api/openapi.yaml`의 OpenAPI 3.1 사양이 권위적입니다.
  요청/응답 유형은 여기에서 생성됩니다. `http/generated/`의
  생성된 유형을 수동으로 편집하지 마십시오.
- 신규 또는 변경된 엔드포인트: 먼저 `api/openapi.yaml`을 업데이트하고,
  재생성한 다음 구현합니다. 코드를 변경하기 전에 Apidog에서 사양을
  설계하고 검토합니다.
- 오류 응답은 RFC 9457 (problem+json)을 따릅니다. 공유된
  `problem()` 헬퍼를 사용하십시오. 즉석 오류 형태를 만들지 마십시오.

## 새로운 코드가 가는 곳

- 새 엔드포인트: `http/routes/`의 라우트, `http/dto/`의 DTO,
  `app/usecases/`의 유스케이스, `domain/`의 도메인 로직.
- 새 외부 통합: `infra/clients/`의 클라이언트,
  `app/ports/`의 인터페이스.
- 교차 관심사 (인증, 로깅, 멱등성): `http/middleware/`의 미들웨어,
  핸들러 내에서 인라인으로 처리하지 마십시오.

## 범위 외 / 건드리지 마시오

- `http/generated/`: OpenAPI에서 재생성되므로, 편집 내용은 손실됩니다.
- `legacy/billing_v1/`: 동결됨, 마이그레이션 중. 확장하지 마십시오.
- `migrations/`: 적용된 마이그레이션을 절대 편집하지 마십시오. 새 마이그레이션을 추가하십시오.

## 의심스러울 때

요청된 변경 사항이 위의 규칙을 위반해야 하는 경우, 올바른 조치는
조용히 규칙을 우회하는 것이 아니라, 그렇게 말하고 가장 작은
설계 일관성 있는 대안을 제안하는 것입니다.

마지막 섹션은 보기보다 중요합니다. 요청이 설계와 충돌할 때 에이전트에게 무엇을 해야 할지 알려주는 것은 파일을 수동적인 문서에서 능동적인 안전장치로 만듭니다. 그것이 없으면, 제약 조건에 부딪힌 에이전트는 그것을 우회하고 해결책을 내놓는 경향이 있습니다.

코딩 에이전트가 실제로 DESIGN.md를 어떻게 소비하는가

에이전트는 특별한 `DESIGN.md` 파서가 없습니다. 에이전트는 다른 파일을 소비하는 것과 같은 방식으로 이를 소비합니다: 파일 도구로 읽고 내용을 컨텍스트로 처리합니다. 따라서 로드하는 방식이 중요하며, 도구마다 약간 다릅니다.

신뢰할 수 있는 패턴은 각 에이전트가 시작 시 이미 로드하는 지침 파일에서 `DESIGN.md`를 참조하는 것입니다. Claude Code의 경우, `CLAUDE.md`입니다. 메모리 문서에는 `@path` 임포트 구문이 설명되어 있으며, `@DESIGN.md`는 세션 시작 시 파일을 컨텍스트로 확장합니다. `AGENTS.md` 생태계의 경우, `AGENTS.md`에 이를 가리키는 줄을 추가합니다 ("아키텍처 및 설계 규칙: `DESIGN.md`를 참조하십시오; 구조적 변경 전에 읽으십시오"). 디렉토리 트리를 탐색하는 에이전트는 가장 가까운 `AGENTS.md`를 찾아 포인터를 확인하고, 작업이 아키텍처와 관련될 때 `DESIGN.md`를 가져옵니다. 어떤 방식이든 콘텐츠를 중복하지 않습니다. 짧은 운영 파일을 짧게 유지하고 심층 파일을 심층적으로 유지하는 것입니다.

이 도구들이 작동하는 방식에서 세 가지 실용적인 참고 사항:

안티 패턴 및 부패 방지

`DESIGN.md`를 가치 없게 만드는 가장 빠른 방법은 위키 페이지처럼 작성하는 것입니다. 부패한 설계 파일은 없는 것보다 나쁩니다. 에이전트와 인간 모두 그것을 신뢰하고 오해하기 때문입니다. 다음 사항을 피하십시오.

건강한 `DESIGN.md`는 짧고, 밀도 높고, 선언적이며, 소유자가 있고, 트리거에 따라 검토됩니다. 만약 당신의 것이 길고, 서술적이며, 마지막으로 1년 전에 수정되었다면, 에이전트는 허구를 읽고 있는 것입니다.

API 및 백엔드 코드베이스를 위한 DESIGN.md

이 파일이 제 역할을 하는 곳입니다. API 및 백엔드 서비스는 에이전트가 가장 취약한, 보이지 않고 비용이 많이 드는 제약 조건(계약 경계, 트랜잭션 의미론, 멱등성, 데이터 무결성, 계층화)을 가지고 있습니다. 이 중 어떤 것도 단일 파일에서 명확하지 않으며, 이를 잘못 처리하면 프로덕션과 금전적 손실로 이어지는 버그가 발생합니다.

`DESIGN.md`에 다음 API 관련 사항들을 넣으면 백엔드 티켓에 대한 에이전트의 결과물 품질이 향상됩니다:

백엔드 작업에서 그 보상은 구체적입니다: 계층 위반 감소, 예상치 못한 인라인 게이트웨이 호출 없음, 일관된 오류 및 페이지네이션 형태, 그리고 에이전트가 스키마를 추측하는 대신 OpenAPI 사양을 따르도록 지시받았기 때문에 계약에 부합하는 핸들러. 에이전트는 발명을 멈추고 규정을 따르기 시작합니다. 에이전트가 방금 작성한 API를 실행하도록 하려면, 계약과 설계를 결합하는 것이 도구와 에이전트가 알려진 인터페이스에 대해 테스트할 수 있도록 하는 것입니다. Apidog 다운로드는 설계 우선 작업 공간, `DESIGN.md`가 가리키는 OpenAPI 내보내기, 그리고 생성된 엔드포인트가 실제로 계약과 일치하는지 확인하는 MCP 서버 및 AI 에이전트 디버거를 제공합니다.

결론

FAQ

DESIGN.md는 AGENTS.md와 같은 공식 표준인가요?

아닙니다. `AGENTS.md`는 Linux Foundation의 Agentic AI Foundation에서 현재 관리하는, 정의되고 널리 채택된 형식입니다. `DESIGN.md`는 `ARCHITECTURE.md` 및 ADRs와 같은 계열에 속하며, 단일 소유자나 사양이 없는 커뮤니티 관례입니다. 준수해야 할 표준이 아니라, 적용할 유용한 패턴으로 취급하세요.

AGENTS.md나 CLAUDE.md가 이미 있다면 DESIGN.md가 필요한가요?

아키텍처에 명확하지 않은 제약 조건이 있다면, 필요합니다. `AGENTS.md`와 `CLAUDE.md`는 짧고 운영적인 상태를 유지하도록 의도되었습니다. Claude Code 문서는 `CLAUDE.md`를 약 200줄 미만으로 유지하도록 권장합니다. 심층적인 아키텍처 근거는 파일을 부풀리고 준수도를 해치지 않고는 거기에 맞지 않으므로, `DESIGN.md`에 넣고 참조합니다. 운영 파일 자체에 대해서는 AGENTS.md 파일 작성 방법을 참조하십시오.

DESIGN.md는 ARCHITECTURE.md와 어떻게 다른가요?

주로 의도와 대상이 다릅니다. `ARCHITECTURE.md`는 코드베이스를 매핑하는 인간 기여자를 대상으로 한 오래된 관례입니다. `DESIGN.md`는 코딩 에이전트를 포함한 대상을 위해 작성된 동일한 아이디어입니다: 더 선언적이고, 결정 및 불변 조건에 중점을 두며, 에이전트 지침 파일에서 명시적으로 참조되어 컨텍스트로 로드됩니다. 많은 팀이 하나의 파일과 하나의 이름을 사용하지만, 원칙은 동일합니다.

DESIGN.md는 얼마나 길어야 하나요?

에이전트가 계속해서 잘못 이해하는 결정들을 다룰 만큼 길고, 모든 줄이 그 자리를 차지할 만큼 짧아야 합니다. 포괄적이기보다는 결정 밀도가 높아야 합니다. 튜토리얼처럼 읽히거나 코드를 반복 설명한다면, 삭제하세요. 불변 조건과 근거에 초점을 맞춘 2~4페이지가 에이전트가 면밀히 읽지 않을 15페이지짜리 서술적인 글보다 낫습니다.

에이전트가 실제로 이것을 읽게 하려면 어떻게 해야 하나요?

에이전트가 시작 시 이미 로드하는 파일에서 이를 참조하십시오. Claude Code의 경우, `CLAUDE.md`에서 `@DESIGN.md`를 사용하여 임포트하십시오. `AGENTS.md` 생태계의 경우, `AGENTS.md`에 구조적 변경 전에 `DESIGN.md`를 읽으라고 에이전트에게 지시하는 포인터 라인을 추가하십시오. 전체 내용을 짧은 파일에 붙여넣지 마십시오. 운영 파일이 짧게 유지되도록 참조하십시오.

에이전트는 항상 DESIGN.md를 따를까요?

아닙니다. 그리고 그렇게 디자인해야 합니다. 에이전트 지침 파일은 모델이 따르려고 노력하는 컨텍스트이지, 강제된 구성이 아닙니다. 규칙을 명확한 절대적인 것으로 작성하고, "충돌 발생 시 플래그 지정, 우회하지 않음"이라는 명시적인 지침을 추가하며, 검토 루프에 의존하십시오. `DESIGN.md`의 위반된 규칙을 지적하면, 첫 번째 시도에서 놓쳤더라도 빠르고 정확한 수정이 이루어집니다.

DESIGN.md가 특히 API 계약 문제에 도움이 되나요?

많이 도움이 됩니다. 가장 가치 있는 백엔드 사용은 OpenAPI 사양이 권위적이며 그 파일 이름을 명시하여, 에이전트가 스키마를 발명하거나 생성된 유형을 수동으로 편집하는 대신 계약에 따르도록 하는 것입니다. Apidog와 같은 도구에서 먼저 계약을 설계하면, `DESIGN.md`가 직접 가리킬 수 있는 명확한 대상을 에이전트에게 제공합니다.

DESIGN.md는 저장소의 어디에 있어야 하나요?

저장소 루트, `README.md` 및 `AGENTS.md` 옆에 두어 에이전트와 인간이 검색 없이 찾을 수 있도록 합니다. 모노레포에서는 시스템 전체 규칙을 위한 루트 `DESIGN.md`와 로컬 아키텍처를 위한 패키지별 `DESIGN.md`가 잘 작동하며, 에이전트가 디렉토리 트리에서 가장 가까운 `AGENTS.md`를 읽는 방식과 유사합니다.

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드