oh-my-design 2.0 설치 실습: DESIGN.md가 아직 없다는 진단의 의미
Codex용 oh-my-design 2.0.0을 실제 설치하고 doctor 결과를 확인했습니다. 설치와 디자인 기준 완성을 구분하고, 기준서와 반응형 HTML 예제를 제공합니다.
- #oh-my-design
- #DESIGN.md
- #디자인 시스템
- #Claude Code
- #Cursor
설치 완료와 디자인 기준 완성은 다른 상태입니다
무료 오픈소스 oh-my-design을 설치하면 AI 코딩 에이전트가 참고할 스킬과 디자인 자료를 프로젝트에 넣을 수 있습니다. 하지만 설치했다고 내 서비스의 DESIGN.md가 완성되는 것은 아닙니다. Windows의 빈 작업 폴더에 2.0.0을 설치하고 진단해 보니 이 차이가 명확했습니다.
이 글에서 직접 확인한 것은 Codex용 설치와 doctor 결과입니다. 아래 화면은 편집팀이 정한 규칙을 HTML에 적용한 작은 예제이며, OmD가 자동 생성했다거나 서로 다른 모델의 디자인 일치도를 측정했다는 뜻은 아닙니다.
별도 폴더에서 Codex용으로 설치했습니다
Node.js와 npm이 있는 환경에서 빈 폴더를 만든 뒤 실행합니다. 이번 검증은 Node 22.17.1, 패키지 oh-my-design-cli@2.0.0 기준입니다. latest 대신 버전을 고정해 같은 명령을 다시 확인할 수 있게 했습니다.
mkdir omd-example
cd omd-example
npx --yes oh-my-design-cli@2.0.0 install-skills --agent codex --all
npx --yes oh-my-design-cli@2.0.0 doctor --json
첫 명령은 현재 프로젝트의 Codex 채널에 설치합니다. --global은 사용하지 않았습니다. 실행 결과는 스킬 22개·에이전트 정의 19개·참고 DESIGN.md 440개였고, 훅은 0개였습니다. 이 숫자는 해당 버전의 관찰값이며 다른 버전의 보장값이 아닙니다.
| 위치 | 이번 설치에서 확인한 내용 |
|---|---|
.agents/skills/ | Codex가 읽을 스킬 |
.codex/agents/ | 에이전트 역할 정의 |
.codex/data/ | 참고 목록과 디자인 자료 |
프로젝트의 DESIGN.md | 아직 없음 |
프로젝트에 파일이 생기는 설치이므로 실제 작업 폴더에 적용하기 전 Git 변경을 확인하는 편이 좋습니다. 다른 도구의 설치 경로나 옵션은 같은 것으로 추정하지 말고 해당 버전 도움말을 보세요.
실제로 막혔던 명령과 올바른 명령
처음에는 설치 명령과 같은 방식으로 doctor --agent codex를 실행했습니다. 결과는 unknown option '--agent'였습니다. doctor는 설치된 채널을 읽으며, 이 버전에서는 해당 옵션을 받지 않습니다.
# 2.0.0에서 실패한 호출
npx --yes oh-my-design-cli@2.0.0 doctor --agent codex
# 실제 진단에 사용한 호출
npx --yes oh-my-design-cli@2.0.0 doctor --json진단에는 Codex 채널 installed: true, ready: true가 나왔지만 프로젝트 상태는 needs-design-md, designMd: false였습니다. 도구 묶음의 준비와 제품의 디자인 기준 준비를 서로 다른 필드로 표시합니다.
진단 결과 JSON을 제공했습니다. 경로는 예제 폴더명으로 정리했고 개인 계정 정보는 넣지 않았습니다. 이 상태에서 “다 끝났다”고 넘기면 다음 에이전트는 여전히 색·간격·컴포넌트의 기준을 추측해야 합니다.
기준 파일에는 색 이름보다 판단 기준을 남깁니다
작은 강의 카드 예제를 생각해 봅시다. “깔끔하게 만들어줘”라는 요청만으로는 모바일 제목 줄바꿈, 가격의 강조, 버튼 높이를 정할 수 없습니다. 그래서 다음 네 가지를 명시했습니다.
| 기준 | 이 예제의 선택 | 이유 |
|---|---|---|
| 제목 | 24px, 줄 높이 1.4, 단어 단위 줄바꿈 | 한국어 제목을 모바일에서 읽기 쉽게 |
| 카드 간격 | 24px 안쪽 여백·16px 요소 간격 | 제목·설명·가격의 묶음 구분 |
| 버튼 | 최소 높이 44px, 키보드 포커스 표시 | 클릭 영역과 현재 위치를 분명하게 |
| 좁은 화면 | 한 열, 고정 카드 폭 금지 | 390px 화면에서 잘림 방지 |
DESIGN.md 학습 예제와 수정 전 HTML, 규칙을 적용한 HTML을 내려받을 수 있습니다. 이 DESIGN.md는 사람이 읽는 간단한 기준서이며, OmD 2.0의 Core v2 포맷 검증이나 채택 절차를 통과한 패키지는 아닙니다.
수정 전 모바일 화면과 아래 수정 후 화면을 비교하면 고정 폭 카드가 넘치던 문제를 확인할 수 있습니다.
디자인 파일을 실제 작업에 연결하는 방법
에이전트에게 기준 파일을 읽고 어떤 항목을 적용했는지 설명하도록 요청합니다. 완성 화면에서는 문서에 적힌 숫자와 실제 CSS·화면을 대조합니다. 버튼 높이를 44px로 써놓고 스타일이 적용되지 않았다면 문서가 있다는 사실만으로 통과시키면 안 됩니다.
이 예제는 고정 폭 560px 카드를 반응형 폭으로 바꾸고, 제목·본문·버튼의 규칙을 적용했습니다. PC와 390px에서 파일을 열어 확인했습니다. 두 HTML은 브라우저에서 독립적으로 열 수 있어 기존 앱 없이도 차이를 볼 수 있습니다.
OmD의 정식 시스템을 만들 때는 설치 후 에이전트를 다시 시작하고 원하는 제품·사용자·참고 스타일을 구체적으로 요청합니다. 프로젝트 신뢰 설정과 도구별 지원 범위를 확인한 뒤, 제시된 변경을 검토하고 채택해야 합니다. 이 글의 간단한 Markdown을 정식 Core v2 파일처럼 덮어쓰지 마세요.
다음 세션에 넘길 때 확인할 것
| 넘기는 자료 | 확인할 질문 |
|---|---|
| 디자인 기준 | 각 선택의 이유와 적용 대상이 있는가 |
| 구현 화면 | PC·모바일에서 기준이 실제로 적용됐는가 |
| 예외 | 이 화면만 다른 부분과 이유를 남겼는가 |
| 진단 결과 | 설치 준비와 디자인 채택 상태를 구분했는가 |
모든 화면을 같은 모양으로 만드는 것이 목적은 아닙니다. 같은 결정을 반복할 때 어떤 근거를 재사용하고, 언제 예외를 허용할지 남기는 것이 중요합니다. 설치 성공 메시지보다 실제 화면과 기준서의 대응 관계가 다음 작업에 더 유용합니다.
문서 결과를 눈으로 검수하는 과정은 OfficeCLI PPT 사례, 반복 지시의 충돌을 줄이는 방법은 컨텍스트 규칙 수정 사례에서 이어집니다.
수정 기록: 최신 README의 기능 목록 중심 설명을 2.0.0의 실제 설치·실패·진단 결과와 별도의 기준 적용 예제로 바꿨습니다.
출처
- oh-my-design 공식 저장소: 설치 채널, DESIGN.md와 정식 시스템 채택 흐름.
- oh-my-design-cli 2.0.0 패키지: 실행 버전. 옵션과 설치 개수는 이 버전의 로컬 실행으로 확인했습니다.
확인 날짜: 2026년 9월 14일. 자동 디자인 생성이나 모델 간 성능 비교는 검증 범위에 포함하지 않았습니다.
자주 묻는 질문
- 설치하면 DESIGN.md도 자동으로 완성되나요?
- 이번 Codex용 설치에서는 스킬과 참고 자료는 준비됐지만 프로젝트 상태는 needs-design-md였습니다. 제품에 맞는 기준을 정하고 채택하는 단계가 따로 필요합니다.
- 첨부된 화면은 OmD가 자동으로 만든 결과인가요?
- 아닙니다. 실제로 실행한 범위는 설치와 doctor 진단입니다. 화면은 편집팀이 작성한 간단한 기준서를 HTML에 적용한 학습 예제이며 Core v2 검증 완료 패키지가 아닙니다.
관련 글
Work Automation
개인정보처리방침을 Claude Code 스킬로 만드는 절차
개인정보처리방침 생성 스킬에 넘길 서비스 사실관계 점검표와 초안 대조 방법입니다. 법령 조건과 확인되지 않은 입력을 구분해 잘못된 고지를 줄입니다.
AI Coding Tools
Anthropic의 프롬프트 80% 축소 사례와 블로그 규칙 충돌 정리
Anthropic의 컨텍스트 엔지니어링 설명을 바탕으로, 실제 블로그 생성 규칙의 글자 수·그림 수·검증 기준 충돌을 찾아 고친 사례를 보여드립니다.