AI 시대 개발팀 운영법: DESIGN.md·테스트·알림을 하나의 검증 흐름으로

AI가 코드를 빨리 만드는 팀일수록 “작성 속도”보다 “틀린 변경을 빨리 막는 구조”가 중요하다. 브랜드와 맞지 않는 UI, 테스트 없이 통과한 코드, 원인만 나열하는 알림은 모두 같은 문제에서 나온다. 에이전트에게 필요한 맥락과 완료 조건, 운영 신호가 한 흐름으로 연결되지 않은 것이다.

실전 상황

에이전트가 로그인 화면을 만들었다. 기능은 작동하지만 버튼 색과 간격이 제품과 다르고, 모바일 테스트가 빠졌으며, 배포 뒤 로그인 오류 알림에는 담당자와 확인 링크가 없다. 코드를 다시 생성하는 것보다 먼저 검증 흐름을 고쳐야 한다.

목차

1. AI 시대에 개발 하네스가 더 중요해진 이유
2. DESIGN.md에 무엇을 넣을 것인가
3. 테스트와 미리보기를 완료 조건으로 만드는 법
4. 알림을 대응 가능한 운영 인터페이스로 바꾸는 법
5. 작은 팀에 적용하는 최소 구조

1. 값싼 초안이 검증 비용까지 없애 주지는 않는다

AI는 첫 코드를 만드는 비용을 낮추지만, 요구사항 해석과 엣지케이스, 접근성, 보안, 운영 책임을 자동으로 확정하지 않는다. 변경량이 늘수록 사람이 모든 줄을 뒤늦게 읽는 방식은 버티기 어렵다. 그래서 규칙을 문서에 남기고 테스트와 미리보기를 자동 실행하며 실패를 담당자에게 연결해야 한다.

의도·제약자동 검사변경 미리보기운영 알림

층	담아야 할 정보	막는 문제
맥락	사용자, 브랜드 원칙, 금지 패턴, 접근성 기준	기능은 되지만 제품답지 않은 결과
검사	타입·단위·통합·접근성·보안 테스트	눈으로 놓치는 회귀와 경계조건
미리보기	실제 화면, 변경 diff, 성능 수치	코드만 보고 승인한 UI·성능 문제
운영	사용자 증상, 심각도, 담당자, 대시보드, 런북	알림은 왔지만 다음 행동을 모르는 상태

2. DESIGN.md는 디자인 시스템 전체 복사가 아니다

Atlassian은 DESIGN.md를 디자인 의도와 핵심 토큰을 옮기기 쉬운 스냅샷으로 설명한다. 내부 실험에서는 자체 MCP·스킬보다 제공되는 컨텍스트가 적었고 토큰과 실행 시간이 더 들었다. 따라서 DESIGN.md는 풍부한 디자인 시스템 도구의 대체재가 아니라, 다른 도구로 옮길 때 최소한의 방향을 보존하는 포맷으로 보는 편이 정확하다.

작은 팀용 DESIGN.md 예시

# Product intent
- 처음 방문한 사용자가 3분 안에 첫 작업을 끝낸다.

# Visual rules
- 본문 최대 폭: 860px
- 모바일 좌우 여백: 19px
- 주 행동 버튼: teal-700, 보조 행동은 테두리 버튼
- 카드 그림자보다 1px 테두리를 우선한다.

# Components
- Button: default / hover / disabled / loading 상태 필수
- Form: label과 오류 문구를 입력칸에 연결한다.

# Avoid
- 의미 없는 그라디언트
- 대문자 영문 장식 제목
- 클릭 불가능한 카드 전체 hover 효과

728x90

색상 숫자만 적으면 에이전트는 언제 그 색을 써야 하는지 모른다. 토큰과 함께 선택 이유, 사용 조건, 금지 사례를 적는다. 실제 컴포넌트와 Storybook·MCP·스킬을 사용할 수 있다면 문서는 그것들을 가리키는 입구가 되어야 한다.

3. 완료 조건은 “코드 작성”이 아니라 증거 묶음이다

에이전트 작업의 완료 보고에는 변경 파일, 실행한 검사, 실제 결과가 있어야 한다. 테스트가 실행되지 않았는데 “문제없음”이라고 쓰는 것을 막으려면 CI가 최종 판단을 맡아야 한다.

완료 조건
1. 타입 검사와 단위 테스트 통과
2. 모바일 390px / 데스크톱 1440px 화면 캡처
3. 접근성 자동 검사에서 새 오류 0개
4. 변경 전후 성능 수치 기록
5. 실패 시 배포 중단
6. 사람이 diff와 화면을 확인한 뒤 승인

사람 검토를 없애는 것이 목적이 아니다.

기계가 반복 가능한 조건을 먼저 검사하면 사람은 사용자 영향, 설계 적합성, 위험한 예외에 시간을 쓸 수 있다.

4. 좋은 알림은 원인이 아니라 사용자 증상에서 시작한다

Google SRE와 Prometheus의 권고는 공통적으로 사용자에게 보이는 증상에 경보를 걸고, 사람이 할 일이 없는 페이지를 만들지 말라고 한다. CPU 사용률 하나가 높다는 이유보다 로그인 실패율과 응답 지연처럼 사용자 영향을 먼저 본다.

나쁜 알림	개선한 알림
CPU 85%	로그인 API p95 2초 초과가 10분 지속, 사용자 실패율 5% 동반
담당자 없음	owner=identity-team과 호출 채널 표시
수치만 전송	영향 범위, 시작 시각, 대시보드·로그·런북 링크 포함
한 번 실패하면 호출	일시적 흔들림을 걸러낼 지속시간과 재시도 고려

alert: LoginFailureRateHigh
condition: error_rate > 0.05 for 10m
labels:
  severity: page
  owner: identity-team
annotations:
  impact: "로그인 사용자 5% 이상 실패"
  dashboard: "/dashboards/login"
  runbook: "/runbooks/login-failure"

알림 규칙도 코드처럼 저장하면 변경 이력, 리뷰, 테스트, 롤백이 가능하다. 다만 IaC로 옮겼다는 사실만으로 좋은 알림이 되지는 않는다. 실제 호출 뒤 “행동 가능했는가?”, “중복 호출이었는가?”를 회고해 임계치와 설명을 조정해야 한다.

5. 작은 팀은 한 저장소에서 최소 구조부터 시작한다

project/
├─ DESIGN.md
├─ AGENTS.md
├─ src/
├─ tests/
├─ .github/workflows/verify.yml
├─ monitoring/alerts.yml
└─ runbooks/login-failure.md

1. 반복되는 UI 실수와 운영 실수를 각각 세 개만 적는다.
2. 문서 규칙, 자동 검사, 알림 중 가장 싼 방어선을 연결한다.
3. PR마다 테스트 결과와 화면을 남긴다.
4. 배포 실패와 실제 장애를 기준으로 규칙을 갱신한다.

핵심 요약

• AI가 초안을 빠르게 만들수록 맥락·검사·미리보기·알림의 연결이 중요하다.
• DESIGN.md는 디자인 시스템의 휴대용 스냅샷이며 풍부한 도구의 대체재가 아니다.
• 완료 여부는 에이전트의 문장이 아니라 테스트와 화면 증거로 판정한다.
• 알림은 사용자 증상, 담당자, 다음 행동을 한 번에 보여 줘야 한다.

참고한 공식 자료

• Atlassian: DESIGN.md 실전 테스트
• Atlassian Design System의 AI 컨텍스트 구조
• Google SRE: Monitoring Distributed Systems
• Prometheus: Alerting practices

확인 기준일: 2026년 7월 28일.