AI 주도 개발은 어떻게 진화하는가 - 하네스 엔지니어링 관점에서 생각하는 AIDD 성숙도 모델 Level 0~3 - 그 두 번째

Level-1c: 설계 문서의 AI 최적화 심층 분석

서론

지난 기사에서는 하네스 엔지니어링 (Harness Engineering)의 관점에서 AIDD의 성숙도 모델을 Level-null부터 Level-3까지 정리했습니다.

다음 기사에서는 Level-2, 즉 애자일 프로세스 (Agile Process)에 AI를 통합해 나가는 단계에 대해 자세히 쓰는 것도 고려했습니다.

하지만 실제로 팀에서 AIDD를 진행하다 보면, Level-2로 나아가기 전에 Level-1의 각 단계를 상당히 세심하게 정비할 필요가 있다고 느낍니다.

Level-1은 단순히 AI 도구를 도입하는 단계가 아닙니다.

AI가 팀의 개발 프로세스에 스며들어 설계, 구현, 리뷰, 테스트, 개선에 관여할 수 있도록 하기 위한 토대 구축입니다.

이 토대가 불충분한 상태에서 Level-2로 나아가려 하면, AI에 의해 구현 속도만 올라가고 설계 품질이나 리뷰 품질이 따라가지 못하게 됩니다.

따라서 이 시리즈에서는 Level-1의 각 단계를 하나씩 심층 분석해 나갈 것입니다.

최종적으로는 이 시리즈를 순서대로 따라 수행하면, AIDD가 개인의 기술이 아니라 팀으로서 기능하는 상태에 가까워질 수 있도록 하는 기사로 만들고자 합니다.

이번에는 Level-1c인 「설계 문서의 AI 최적화」를 다룹니다.

지난 내용 복습: Level-1에서 수행하는 것

지난 기사에서는 Level-1을 다음과 같이 정리했습니다.

• Level-1a: Guides 작성 및 도구 통합
• Level-1b: 회의체 창출 및 PDCA 루틴 확립
• Level-1c: 설계 문서의 AI 최적화
• Level-1d: Sensors 재검토
• Level-1e: Guides 재설계
• Level-1f: 프롬프팅 (Prompting) 리뷰 실시
• Level-1g: 보안 및 개발 환경 재검토
• Level-1h: 소프트웨어의 AI 최적화 리팩터링 (Refactoring)
• Level-1i: 멀티 에이전트 (Multi-agent) 개발과 리소스 제약

이번에는 이 중에서 Level-1c: 설계 문서의 AI 최적화를 심층 분석합니다.

설계 문서의 AI 최적화란 무엇인가

AIDD를 진행하다 보면, AI가 생성하는 코드의 품질이 프롬프트 (Prompt)만으로 결정되는 것이 아니라는 사실을 깨닫게 됩니다.

AI가 참조할 수 있는 설계 문서의 질에 따라 생성되는 코드의 품질은 크게 달라집니다.

예를 들어, 다음과 같은 상태에서는 AI가 정확한 구현을 수행하기 어려워집니다.

• DB 구조가 Excel에만 존재하는 경우
• API 사양이 오래된 Wiki에만 남아 있는 경우
• ERD (Entity-Relationship Diagram)가 이미지 파일로만 존재하는 경우
• 인프라 구성이 담당자의 머릿속에만 있는 경우
• 화면 목록이나 라우팅 (Routing) 정보가 정리되어 있지 않은 경우
• 업무 용어의 의미가 SaaS 매뉴얼이나 담당자의 암묵지에 갇혀 있는 경우
• Figma, Notion, GitHub에 정보가 분산되어 있는 경우

AIDD에서의 설계 문서 최적화는 단순히 설계서를 깔끔하게 만드는 것이 아닙니다.

AI가 올바르게 읽을 수 있고, 인간도 리뷰할 수 있으며, 구현 및 테스트에 연결할 수 있는 형태로 설계 정보를 재구성하는 것입니다.

기본 원칙: AI가 읽기 쉽고, 인간도 읽기 쉬울 것

설계 문서를 AI 최적화할 때 중요한 것은 AI가 읽기 쉬운 것과 인간이 읽기 쉬운 것을 양립시키는 것입니다.

AI가 읽기 쉽더라도 인간이 읽을 수 없는 형식이라면 의미가 없습니다.

거대한 JSON 파일에 모든 설계 정보를 채워 넣으면 AI는 읽을 수 있을지도 모릅니다.

하지만 인간이 리뷰할 수 없는 형식이라면 그 설계서는 금방 업데이트되지 않게 됩니다.

반대로 인간에게는 보기 좋지만 AI가 읽기 어려운 문서도 문제입니다.

대표적인 예는 Excel, PowerPoint, 이미지화된 ERD, 스크린샷 중심의 사양서입니다.

이것들은 인간에게는 보기 편할 수 있지만, AI에게는 구조화된 정보로 다루기 어렵습니다.

기본 방침은 다음과 같습니다.

• 바이너리 (Binary) 형식을 피한다
• GitHub에서 차분 관리 (Diff management)할 수 있는 형식을 우선한다
• Markdown, YAML, DDL, Mermaid 등의 텍스트 기반 형식을 우선한다
• 단, 인간이 읽을 수 없는 생데이터 (Raw data) 형식으로만 만들지는 않는다
• IDE나 GitHub 상에서 읽기 쉽게 렌더링할 수 있는 형식을 채택한다
• AI에게 읽힐 정보와 은닉해야 할 정보를 분리한다

즉, 내부 구조로는 AI가 읽기 쉬운 형식으로 유지한다.

한편, 인간은 IDE, GitHub, Notion, 프리뷰 (Preview) 기능, 전용 플러그인 등을 통해 읽기 쉽게 확인할 수 있도록 한다.

이러한 양립이 설계 문서의 AI 최적화에 있어 기본 원칙입니다.

설계 문서 최적화 우선순위 표

설계서명	최적화 우선순위	GitHub 관리	권장 형식	이유
DB 설계서: 테이블 구조 정의서	★★★★★	필수	Markdown / DDL / Schema 정의	이것이 없으면 AI가 DB를 전제로 한 구현을 올바르게 수행할 수 없음
...

DB 설계서: 테이블 구조 정의서의 AI 최적화

가장 우선순위가 높은 것은 DB 설계서입니다.

특히 테이블 구조 정의서가 정비되지 않은 상태에서는 AIDD가 제대로 기능하지 못한다고 해도 과언이 아닙니다.

AI는 코드만 보고는 DB의 의미까지 완전히 이해할 수 없습니다.

컬럼명(Column name), 타입(Type), NULL 허용 여부, 기본값(Default value), 인덱스(Index), 외래 키(Foreign key), 업무상의 의미 등이 정리되어 있지 않으면 AI는 추측에 의존하여 구현하게 됩니다.

추측으로 구현된 코드는 처음에는 그럴싸하게 동작할지 몰라도, 나중에 불일치를 일으키기 쉽습니다.

권장 형식은 Markdown, DDL, schema 정의 등입니다.

중요한 것은 AI가 읽을 수 있을 뿐만 아니라, 인간이 차이(Diff)를 리뷰할 수 있어야 한다는 점입니다.

Excel 기반의 DB 정의서는 차이 관리가 어렵고 AI가 읽기에도 까다롭기 때문에 AIDD에는 적합하지 않습니다.

DB 설계서에는 최소한 다음 내용이 포함되어야 합니다.

• 테이블명
• 테이블의 역할
• 컬럼명
• 데이터 타입
• NULL 허용 여부
• 기본값
• 기본 키 (Primary key)
• 외래 키 (Foreign key)
• 인덱스
• 유니크 제약 조건 (Unique constraint)
• 업무상 중요한 컬럼의 의미
• AI가 실수하기 쉬운 주의사항

특히 중요한 것은 물리적 구조뿐만 아니라 의미 정보를 작성하는 것입니다.

user_id, account_id, member_id, student_id와 같이 유사한 개념이 존재하는 경우, 인간도 혼란을 느낍니다.

AI는 더욱 혼란스러워하기 쉽습니다.

따라서 DB 설계서에 "이 ID는 무엇을 의미하는가", "유사한 컬럼과 무엇이 다른가"까지 적어두면 AI의 구현 정밀도가 높아집니다.

API 설계서의 AI 최적화

API 설계서도 필수입니다.

특히 프론트엔드와 백엔드가 분리된 개발에서는 API 설계서가 정비되어 있지 않으면 AI가 올바르게 구현할 수 없습니다.

REST API라면 OpenAPI YAML을 권장합니다.

OpenAPI YAML은 인간이 읽을 수 있을 뿐만 아니라, AI가 구조적으로 해석하기 쉽고 GitHub에서 차이 관리가 가능합니다.

Swagger UI 등을 통해 읽기 쉽게 렌더링할 수 있으며, 모크(Mock), 타입 생성, 테스트 생성 등으로 연결하기 쉬운 형식입니다.

API 설계서에는 최소한 다음 내용이 포함되어야 합니다.

• 엔드포인트 (Endpoint)
• HTTP 메서드 (Method)
• 요청 파라미터 (Request parameter)
• 요청 바디 (Request body)
• 응답 형식 (Response format)
• 상태 코드 (Status code)
• 에러 코드 (Error code)
• 에러 메시지 (Error message)
• 인증 및 인가 (Authentication/Authorization)
• 유효성 검사 규칙 (Validation rule)
• 페이지네이션 (Pagination)
• 정렬 및 필터 조건

여기서 중요한 것은 에러 코드, 에러 메시지, 유효성 검사 사양을 API 설계서의 일부로 다루는 것입니다.

이것들을 API 설계서와 분리해 버리면, AI가 API 구현, 화면 측의 에러 핸들링, 테스트 코드를 생성할 때 사양의 정합성이 깨지기 쉽습니다.

예를 들어, 입력 에러 시 어떤 상태 코드를 반환할지, 어떤 에러 코드를 반환할지, 화면에 어떤 메시지를 표시할지가 모호하면 AI는 그 상황에서 추측하여 구현해 버립니다.

API 설계서는 AI에게 구현 계약서입니다.

계약서가 모호하면 AI의 구현도 모호해집니다.

인프라 설계서의 AI 최적화

인프라 설계서의 우선순위도 높습니다.

특히 AWS Lambda, AWS Batch, ECS, S3, SQS, EventBridge 등 클라우드 서비스에 의존하는 개발에서는 인프라 설계서가 없으면 AIDD가 어려워집니다.

AI는 코드만 보고는 어떤 AWS 리소스와 연결되는지, 어떤 권한이 필요한지, 어떤 환경 변수가 필요한지를 정확하게 판단할 수 없습니다.

인프라 설계서에는 다음과 같은 정보를 작성하는 것이 유효합니다.

• 시스템 구성
• 사용 중인 AWS 서비스
• 각 서비스의 역할
• 서비스 간의 연결 관계
• 환경 변수 키 이름
• 필요한 권한의 종류
• 로그 출력처
• 모니터링 및 알람 방침
• 배포 방법
• 운영(Production), 스테이징(Staging), 개발(Development) 환경의 차이
• 구현 시 주의사항

인프라 설계서가 정비되어 있으면, AI는 단순히 코드를 작성하는 것에 그치지 않고 AWS 상에서의 설정 작업 가이드까지 제시할 수 있게 됩니다.

Lambda나 Batch 구현에서는 코드만으로는 완성되지 않습니다.

IAM 권한, 환경 변수, 타임아웃, 메모리, VPC 설정, 로그, 재시도(Retry), 이벤트 규칙 등이 모두 갖춰져야 비로소 동작합니다.

인프라 설계서는 AI가 "코드 외부에 있는 실행 조건"을 이해하기 위한 중요한 문서입니다.

GitHub 관리 시 기재하지 않는 것이 좋은 정보

반면, 인프라 설계서를 GitHub에서 관리할 경우에는 보안에 주의해야 합니다.

기본 방침은 구성이나 제약 사항은 작성하되, 실제 값이나 기밀 정보는 작성하지 않는 것입니다.

GitHub에 작성해야 할 내용은 어떤 AWS 서비스를 사용할지, 각 서비스의 역할, 처리 흐름, 환경 변수의 키(Key) 이름, 필요한 권한의 종류, 구현상의 제약 사항입니다.

반대로, 아래 사항은 원칙적으로 작성하지 않는 것이 좋습니다.

• AWS 계정 ID
• VPC ID / Subnet ID / Security Group ID
• RDS나 ElastiCache의 실제 엔드포인트(Endpoint)
• S3 버킷의 실제 이름
• Secret 명칭이나 Parameter Store의 실제 경로
• Webhook URL
• API 키나 액세스 토큰(Access Token)
• 관리 화면 URL
• IP 주소 제한의 구체적인 허용 리스트
• 공격에 악용될 수 있는 장애 대응 절차의 상세 내용

AI에게 필요한 것은 운영 환경의 구체적인 ID나 엔드포인트가 아닙니다.

AI에게 필요한 것은 구성, 역할, 의존 관계, 제약 사항, 환경 변수의 키 이름, 필요한 권한의 종류입니다.

예를 들어, 다음과 같은 방식으로 작성하는 것만으로도 충분합니다.

DB 접속 정보는 `DB_HOST`, `DB_USER`, `DB_PASSWORD`로부터 가져온다.
실제 값은 AWS Secrets Manager에서 관리한다.
Slack 알림용 Webhook은 `SLACK_WEBHOOK_URL`로부터 가져온다.
...

인프라 설계서의 AI 최적화에서는 AI에게 무엇을 읽게 할 것인가뿐만 아니라, AI에게 무엇을 읽히지 않을 것인가도 설계해야 합니다.

SaaS 매뉴얼 / 도메인 사전의 AI 최적화

AIDD에서 SaaS 매뉴얼이나 도메인 사전도 매우 유익합니다.

AI는 코드의 구조를 읽는 데는 능숙하지만, 업무 용어나 제품 고유의 개념을 자연스럽게 이해할 수 있는 것은 아닙니다.

예를 들어, e러닝 계열의 SaaS라면 다음과 같은 용어들이 있습니다.

• 사용자
• 수강자
• 관리자
• 법인 관리자
• 강좌
• 코스
• 커리큘럼
• 섹션
• 레슨
• 수강 이력
• 수료
• 인증서

이러한 용어들은 비슷해 보여도 의미가 다릅니다.

사람도 혼란스러워하기 쉬운 개념은 AI도 당연히 혼란스러워합니다.

따라서 용어의 의미와 사용 구분(使い分け)이 정리된 문서는 AI의 구현 정밀도를 높이는 데 큰 효과가 있습니다.

단, 반드시 처음부터 도메인 사전을 별도로 만들 필요는 없습니다.

SaaS 매뉴얼이 이미 존재하고, 그것이 AI가 해석하기 쉬운 형태로 관리되고 있다면 우선 그것을 활용해야 합니다.

예를 들어, 매뉴얼이 Markdown, Notion, Docs 등으로 구조화되어 있고 화면 명칭, 기능 명칭, 용어, 조작 흐름이 정리되어 있다면 AI에게 매우 유익한 컨텍스트(Context)가 됩니다.

반대로 매뉴얼이 PDF, 이미지, 오래된 HTML, 스크린샷 중심의 자료 등으로 되어 있어 AI가 해석하기 어렵다면, 그 핵심 내용을 추출하여 도메인 사전을 만들 가치가 있습니다.

중요한 것은 SaaS 매뉴얼인지 도메인 사전인지 하는 형식이 아닙니다.

AI가 제품 고유의 개념을 오해하지 않는 상태를 만드는 것입니다.

매뉴얼이 AI가 해석하기 쉬운 형태로 관리되고 있다면 그것이 가장 자연스럽습니다.

그것이 어렵다면 매뉴얼의 핵심 내용을 추출한 도메인 사전을 만들어야 합니다.

화면 목록 · 라우팅 목록의 AI 최적화

화면 목록이나 라우팅 목록 또한 AIDD에서 유익합니다.

특히 프론트엔드 개발에서는 AI가 "어떤 화면이 무엇을 하는지", "어떤 URL이 어떤 컴포넌트(Component)에 대응하는지"를 이해할 수 있느냐에 따라 구현 정밀도가 크게 달라집니다.

화면 목록에는 다음과 같은 정보를 정리합니다.

• 화면 명칭
• URL / 루트(Route)
• 대응하는 컴포넌트
• 화면의 목적
• 이용하는 API
• 필요한 권한
• 주요 입력 항목
• 주요 표시 항목
• 이전 화면 · 다음 화면(遷移元・遷移先)
• 관련 업무 용어

화면 목록이 있으면, AI는 프론트엔드 (Frontend) 수정 시 대상 화면의 역할이나 주변 화면과의 관계를 파악하기 쉬워집니다.

또한, API 설계서나 DB 설계서와 조합함으로써 AI는 「화면」 「API」 「DB」의 연결성을 이해하기 쉬워집니다.

이는 특히 기존 화면의 개수나 유사 화면의 추가에 효과적입니다.

단순히 Figma만 있는 상태보다, 화면 목록과 라우팅 (Routing) 목록이 있는 편이 AI는 구현에 필요한 구조를 이해하기 쉬워집니다.

DB 설계서: ER 다이어그램 (ER Diagram)의 AI 최적화

ER 다이어그램은 테이블 구조 정의서만큼 필수적이지는 않습니다.

하지만 우선순위는 높습니다.

왜냐하면 ER 다이어그램이 있으면 AI는 테이블 간의 관계를 조감도적으로 이해할 수 있기 때문입니다.

특히 신규 테이블 설계나 기존 테이블에 컬럼 (Column)을 추가할 때는 ER 다이어그램의 유무에 따라 AI의 제안 품질이 크게 달라집니다.

권장 형식은 Mermaid, PlantUML, dbdiagram 형식 등입니다.

이미지 파일로만 관리하는 것은 피하는 것이 좋습니다.

이미지는 사람에게는 보기 편할지 몰라도, AI가 차분 (Diff)이나 의미를 다루기 어렵기 때문입니다.

ER 다이어그램은 AI가 「어느 테이블이 어떤 업무 개념에 대응하는지」를 파악하는 데 도움이 됩니다.

예를 들어, 수강자, 강좌, 레슨, 수강 이력, 결제, 법인 계약과 같은 관계가 있는 시스템에서는 단일 테이블 정의만으로는 전체상을 볼 수 없습니다.

ER 다이어그램을 통해 전체상이 보이면, AI는 기존 설계와 정합성을 맞춘 제안을 하기 쉬워집니다.

UML: 시퀀스 다이어그램 (Sequence Diagram)의 AI 최적화

시퀀스 다이어그램의 우선순위는 중간 정도입니다.

단순한 CRUD 처리라면 시퀀스 다이어그램을 만들 필요는 그리 많지 않습니다.

반면, 여러 서비스를 가로지르는 처리, 비동기 (Asynchronous) 처리, 외부 API 연동, 복잡한 OOP 구조에서는 시퀀스 다이어그램이 도움이 되는 경우가 있습니다.

권장 형식은 Mermaid sequenceDiagram이나 PlantUML입니다.

GitHub에서 관리할지 여부는 케이스 바이 케이스 (Case by case)입니다.

일시적으로 AI에게 작성하게 한 뒤 Notion 등에 붙여넣고, 사람이 구조 설계를 리뷰하는 것만으로도 의미가 있습니다.

AIDD에서는 시퀀스 다이어그램의 역할이 조금 달라집니다.

이전에는 사람이 복잡한 처리를 이해하기 위해 시퀀스 다이어그램을 작성했습니다.

AIDD에서는 AI에게 시퀀스 다이어그램을 작성하게 하고, 그것을 사람이 리뷰하는 방식도 유효합니다.

즉, 시퀀스 다이어그램은 「AI에게 구현시키기 위한 사양서」인 동시에, 「사람이 AI의 설계 이해도를 확인하기 위한 리뷰 자료」이기도 합니다.

UI 설계서의 AI 최적화

UI 설계서의 AI 최적화 우선순위는 낮은 편입니다.

특히 웹 애플리케이션 (Web Application) 개발에서는 정적인 UI 설계서를 정비하는 것보다, AI에게 모크 UI (Mock UI)를 구현하게 하는 것이 더 빠를 때가 있습니다.

Figma로 세밀하게 화면을 만들 시간이 있다면, React나 Vue로 동작하는 모크 (Mock)를 만드는 것이 AI와 사람 모두에게 유익할 수 있습니다.

Figma를 GitHub에서 관리할 필요도 기본적으로는 없습니다.

UI 설계는 코드, Storybook, 컴포넌트 카탈로그 (Component Catalog), 구현된 모크와 연결하여 생각하는 것이 현실적입니다.

다만, Figma 자체가 불필요하다는 의미는 아닙니다.

Figma MCP 서버와 같이 AI 에이전트 (AI Agent)가 Figma 상의 디자인 정보를 참조할 수 있는 메커니즘은 유익합니다.

이는 디자이너가 Figma 중심으로 작업하고 있으며, 아직 정적 HTML이나 React / Vue 모크를 만들 수 없는 팀에서는 특히 효과적입니다.

AI가 스크린샷을 보고 추측하는 것보다, Figma MCP 서버를 통해 구조화된 디자인 정보를 참조할 수 있는 편이 UI 구현의 정밀도는 올라갑니다.

한편, AIDD 시대의 이상적인 형태를 생각하면, 디자이너가 완전히 Figma에만 국한되는 것은 점차 한계가 올 것이라고 생각합니다.

AI가 구현까지 지원할 수 있는 시대에는 디자이너도 정적 HTML 정도의 모크, 혹은 간단한 React / Vue 컴포넌트 프로토타입을 만들 수 있는 편이 개발 팀 전체의 생산성을 높입니다.

왜냐하면 UI는 겉모습뿐만 아니라 상태, 데이터, 이벤트, 유효성 검사 (Validation), API 연동과 불가분하기 때문입니다.

Figma 상의 겉모습만으로는 다음과 같은 정보가 부족하기 쉽습니다.

• 어떤 상태에서 어떤 표시가 되는가
• 입력값에 대해 어떤 유효성 검사가 실행되는가
• 버튼 클릭 시 어떤 API를 호출하는가
• 로딩 중이나 에러 시에 어떻게 표시하는가
• 권한에 따라 표시가 어떻게 변하는가
• 기존 컴포넌트를 어떻게 사용하는가

Figma MCP 서버는 Figma 중심의 팀이 AIDD에 접속하기 위한 유력한 보조선입니다.

하지만 본래 AIDD 시대에 지향해야 할 것은 Figma를 AI에게 읽히는 것 그 자체가 아닙니다.

디자이너, 엔지니어, AI가 동일한 UI 구조를 이해할 수 있도록, 정적 디자인에서 움직이는 모크(Mock)나 컴포넌트 기반(Component-based) 설계로 다가가는 것입니다.

UML: 클래스 다이어그램 (Class Diagram)의 AI 최적화

클래스 다이어그램의 우선순위는 낮습니다.

적어도 당사에서는 클래스 다이어그램을 거의 작성하지 않습니다.

그 이유는 현대적인 코드베이스(Codebase)에서는 파일명, 폴더 구조, 타입 정의(Type definition), 인터페이스(Interface), 스키마(Schema), 구현 패턴(Implementation pattern)을 통해 AI가 상당 부분을 이해할 수 있기 때문입니다.

물론 클래스 다이어그램이 유효한 케이스도 있습니다.

예를 들어, 레거시 OOP 구조가 복잡한 경우, 상속 관계가 깊은 경우, 도메인 모델(Domain model)이 복잡한 경우, 신입 사원이나 비엔지니어에게 구조를 설명해야 하는 경우입니다.

하지만 많은 프로젝트에서는 클래스 다이어그램을 그리는 것보다 폴더 구조, 파일 명명, 타입 정의, 인터페이스, 스키마, README, 구현 샘플, 테스트 코드를 정비하는 것이 더 효과적입니다.

AI에게는 구현과 괴리된 클래스 다이어그램보다, 실제로 참조할 수 있는 코드 구조가 더 신뢰도가 높습니다.

이번 기사에서 다루지는 않지만, 다른 단계에서 검토해야 할 것들

지금까지 설계 문서의 AI 최적화라는 관점에서 정리해 왔습니다.

한편, AIDD를 팀에서 기능하게 하려면 설계서 이외에도 중요한 문서나 메커니즘이 있습니다.

예를 들어, 다음과 같은 것들입니다.

• 코딩 규약 (Coding convention)
• 디렉토리 구성 가이드 (Directory structure guide)
• 구현 패턴 모음 (Implementation pattern collection)
• 테스트 방침 (Test policy)
• CLAUDE.md
• 리뷰 관점 (Review perspective)
• 프롬프트 템플릿 (Prompt template)
• 샘플 구현 (Sample implementation)
• 베스트 프랙티스 (Best practice) 모음

이것들도 AIDD에는 매우 중요합니다.

다만, 이것들은 이번 테마인 '설계 문서'라기보다는 Guides, Sensors, 또는 소프트웨어의 AI 최적화 리팩터링(Refactoring) 영역에 가깝다고 생각합니다.

예를 들어, 코딩 규약이나 CLAUDE.md는 Level-1e: Guides의 재설계에서 다루어야 할 테마입니다.

테스트 방침은 Level-1d: Sensors의 재검토에서 다루어야 할 테마입니다.

샘플 구현이나 베스트 프랙티스 모음은 Level-1h: 소프트웨어의 AI 최적화 리팩터링에 가까운 테마입니다.

따라서 이번 기사에서는 어디까지나 'AI가 설계 정보를 올바르게 이해하기 위한 문서'로 범위를 좁혀 정리했습니다.

요약: 설계서는 AI를 위한 프롬프트 자산이 된다

설계 문서의 AI 최적화란 단순히 Excel 설계서를 Markdown으로 변환하는 것이 아닙니다.

설계 정보를 AI와 인간 모두가 지속적으로 읽을 수 있는 형태로 바꾸는 것입니다.

AIDD에서 설계서는 단순한 납품물이 아닙니다.

AI에게는 구현 판단의 전제이며, 프롬프트 자산이며, 팀의 암묵지를 형식지로 바꾸기 위한 하네스(Harness)입니다.

특히 우선순위를 두어야 할 것은 다음 세 가지입니다.

• DB 설계서
• API 설계서
• 인프라 설계서

이 세 가지만 제대로 정비되어도 AI가 생성하는 코드의 품질은 크게 달라집니다.

나아가 SaaS 매뉴얼이나 도메인 사전, 화면 목록, ER 다이어그램(ER Diagram), 시퀀스 다이어그램(Sequence diagram)을 적절히 정비하면 AI는 프로덕트 전체를 더욱 정확하게 이해할 수 있게 됩니다.

반면, UI 설계서나 클래스 다이어그램에 대해서는 반드시 무거운 설계서를 만들 필요는 없습니다.

AIDD에서는 설계 문서도 비용 대비 효과(Cost-effectiveness) 측면에서 생각해야 합니다.

중요한 것은 설계서를 늘리는 것이 아닙니다.

AI와 인간이 동일한 전제를 공유할 수 있는 상태를 만드는 것입니다.

그 상태를 만드는 것이 Level-1c: 설계 문서의 AI 최적화의 목적입니다.

다음 예고

다음 회차에서는 Level-1d: Sensors의 재검토에 대해 심도 있게 다룹니다.

AI에게 설계 정보를 올바르게 전달할 수 있게 되었다 하더라도, AI가 생성한 결과물을 검증하는 메커니즘이 약하면 품질은 안정되지 않습니다.

테스트, Lint, 타입 정의, 스키마 검증(Schema validation), CI/CD 등을 AIDD를 전제로 어떻게 재검토해야 하는지 정리하겠습니다.

함께 일할 동료를 찾고 있습니다

이 기사를 읽고 저나 당사의 엔지니어 팀에 관심이 생기신 분은 꼭 한번 이야기 나누었으면 합니다.

Discussion