kwakseongjae/oh-my-design 딥다이브
— "에이전트에게 디자인 규칙서를 쥐여주다" DESIGN.md 워크플로

1한 줄 정체

oh-my-design은 "디자인 시스템 설치기"다. npx oh-my-design-cli@latest 한 번이면 지금 쓰는 코딩 에이전트(Claude Code / Codex / OpenCode / Cursor) 안에 20개 스킬 · 최대 18개 전문 서브에이전트 · 자동 훅 · 440개 기업 레퍼런스 카탈로그가 깔린다. 이후 사용자가 "우리 서비스 디자인 시스템 세팅해줘"라고 말하면, 방금 설치된 omd:init 스킬이 카탈로그에서 어울리는 기업(예: 토스, 뱅크샐러드, Linear)을 추천하고, 선택된 레퍼런스의 톤을 보존한 변형본을 프로젝트 루트 DESIGN.md로 만들어낸다.

중요한 건 이 도구가 새 AI를 추가하지 않는다는 점이다. 추천 로직도, 문서 작성도 전부 사용자가 이미 쓰고 있는 에이전트의 모델이 스킬 마크다운에 적힌 절차를 그대로 따라가며 수행한다. oh-my-design은 그 절차서(SKILL.md)와 근거 자료(레퍼런스 카탈로그)를 만들어 설치해줄 뿐이다.

2왜 지금 뜨는가

2025~2026년은 Claude Code · Codex · OpenCode 같은 터미널 코딩 에이전트가 일상 도구가 된 시기다. 코드 생성은 빨라졌지만, "디자인 판단"은 여전히 매 프롬프트마다 즉흥적으로 이뤄진다. "미니멀하게", "토스 느낌으로" 같은 지시는 세션이 바뀌면 다시 처음부터 설명해야 하고, 팀원마다 해석이 달라 결과물이 들쭉날쭉해진다. oh-my-design은 이 틈을 정확히 겨냥한다.

① "vibe coding"에 빠진 "vibe design" 문제 해결

코드에는 eslint·prettier·타입 체커 같은 일관성 강제 장치가 있지만, "이 버튼이 우리 브랜드다운가"에는 그런 장치가 없었다. oh-my-design은 DESIGN.md라는 파일을 프로젝트에 커밋시켜, 디자인 판단도 코드처럼 버전 관리되고 다음 세션에서 다시 읽히는 문서로 만든다.

② 레퍼런스가 "검증됨"을 표방한다

단순 "느낌적인 느낌"이 아니라, 각 기업 레퍼런스는 실제 라이브 사이트의 computed-style 스크래핑과 공식 디자인 시스템 문서를 근거로 토큰 값에 출처(source)·방법(method)·날짜(captured)를 매긴다. 한국 기업 레퍼런스는 "브랜드 소유 Tier-1 출처 2개 이상 + Proof 블록"이라는 자체 품질 게이트를 통과해야 카탈로그에 들어간다(CHANGELOG 기준). "그럴듯한 색상 팔레트"가 아니라 "이 회사가 실제로 이 값을 쓴다는 근거"를 파는 셈이다.

③ 멀티 에이전트 시대의 "한 곳에서 관리" 요구

같은 팀 안에서도 누구는 Claude Code, 누구는 Codex, 누구는 Cursor를 쓴다. oh-my-design은 하나의 DESIGN.md를 4개 채널이 공유하게 만들어, 도구가 달라도 같은 브랜드 규칙을 참조하게 한다.

3무엇을 해결하나

실제로 해결하는 문제는 셋으로 요약된다.

문제 ① — 디자인 컨텍스트가 세션 사이에서 증발한다

코딩 에이전트는 대화가 끝나면 그 세션의 판단(어떤 파란색을 썼는지, 왜 그 폰트 크기를 골랐는지)을 잊는다. oh-my-design은 그 판단을 DESIGN.md라는 파일로 프로젝트에 남겨, 다음 세션·다음 사람이 다시 그 파일을 Read하면 동일한 맥락을 되찾게 한다.

문제 ② — "느낌"만으로는 재현이 안 된다

"토스 같은 느낌"이라는 지시는 사람마다, 세션마다 다르게 해석된다. 440개 기업의 검증된 실제 토큰·보이스·원칙을 출발점으로 제공함으로써, "느낌"이 아니라 "이 회사의 실제 값을 기준으로 우리 것을 만든다(hybrid variation)"는 재현 가능한 절차로 바꾼다.

문제 ③ — 여러 에이전트·여러 팀원 간 규칙 파편화

Claude Code용 지시, Codex용 지시, Cursor용 규칙을 따로 관리하면 셋이 어긋난다. oh-my-design은 CLAUDE.md / AGENTS.md / .cursor/rules/omd-design.mdc 세 개의 "shim"(연결 통로) 파일을 자동 생성·동기화해, 진짜 소스는 DESIGN.md 하나로 유지한다.

4전체 구조

저장소는 겉보기엔 npm 패키지 하나(oh-my-design-cli)지만, 실제로는 서로 다른 세 가지 산출물이 한 레포에 같이 산다: ① Node/TypeScript로 짠 설치·진단 CLI, ② 코드가 아니라 마크다운으로 쓰인 절차서(스킬·서브에이전트), ③ Next.js로 만든 웹사이트 겸 레퍼런스 파이프라인(oh-my-design.kr). 이 셋의 관계를 그림으로 보면 아래와 같다.

세 계층은 완전히 다른 언어로 짜여 있다는 게 이 레포의 특징이다. ①은 평범한 TypeScript CLI, ②는 실행 가능한 산문(prose-as-program), ③은 표준적인 Next.js 앱이다. "어디에 로직이 있나"를 코드에서만 찾으면 ②를 놓친다.

5핵심 설계·동작 원리

이 레포에서 배울 가치가 가장 큰 설계는 코드의 복잡도가 아니라 "신뢰를 어떻게 기계적으로 보장하는가"다. 네 가지 패턴으로 나눠본다.

설계 패턴 ① — sha256 마커로 "내가 관리하는 파일"과 "사용자가 고친 파일"을 구분한다

src/cli/hook-contract.ts는 설치되는 훅 6개(skill-activation.cjs 등) 각각에 대해, 파일 맨 위에 // omd:installed-hook sha256=<해시>라는 한 줄을 새긴다. 이 해시는 마커를 뺀 나머지 내용으로 계산되므로(renderManagedHook), 파일을 열어 실제로 재계산해보면 "이 파일이 지금 배포되는 버전 그대로인지, 사용자가 손을 댔는지"를 판별할 수 있다(isCurrentManagedHook). 과거 버전(마커가 없던 시절) 파일까지 LEGACY_HOOK_HASHES 해시 목록으로 인식해, 재설치 시 "이건 예전 관리 파일이니 갱신해도 안전"이라고 판단한다.

설계 패턴 ② — 추천·추론 로직이 코드가 아니라 "실행되는 산문"으로 존재한다

skills/omd-init/SKILL.md는 약 320줄짜리 마크다운인데, 이 자체가 7단계 상태 기계다. TypeScript 함수가 아니라 "다음 순서로 하라"는 지시문으로 짜여 있고, 이를 실제로 실행하는 건 호스트 에이전트(Claude Code 등)의 LLM이다.

• Phase 1 — 프로젝트 유형·분위기 키워드를 최대 2개 질문으로 파악.
• Phase 2 — data/reference-fingerprints.json을 읽어, "브랜드명 언급 +5점 / 톤 키워드 일치당 +1점 / 카테고리 일치 +1점"이라는 결정론적 점수 규칙을 LLM이 머릿속으로(in-head) 계산해 상위 5개를 추천.
• Phase 3~3.5 — 사용자가 하나를 고르고, "프로젝트 표준으로 적용" 또는 "참고용으로만 저장"을 선택.
• Phase 4 — 선택된 기업의 원본 DESIGN.md를 정해진 우선순위 경로(.codex/data → .claude/data → .opencode/data → node_modules → 개발 레포 → 그래도 없으면 oh-my-design.kr/<id>/design.md 원격 fetch)로 찾는다. 전부 실패하면 "절대 지어내지 말고 사용자에게 실패를 알리라"고 명시돼 있다.
• Phase 4.5 — 브랜드 서사(§11~13)에 들어갈 실제 사실(프로젝트명·창립 시점·핵심 테제)을 사용자에게 묻고, "skip" 응답 시 내용을 지어내는 대신 [FILL IN: …] 플레이스홀더 + <!-- omd:limitation --> 주석을 넣도록 강제한다.
• Phase 5 — "하이브리드 변형" 생성. 레퍼런스의 제목 구조는 그대로 두고 명사만 교체(동사·형용사·문체는 그대로)하는 엄격 규칙, 그리고 토큰 값 우선순위(라이브 실측값 > 레퍼런스 canonical 값 > 사용자 delta)를 강제한다.
• Phase 6~7 — omd:sync 스킬에 위임해 CLAUDE.md/AGENTS.md/Cursor rule shim을 갱신하고 요약을 출력.

이 절차서는 스스로에게 "금지 목록"도 박아둔다 — 예컨대 "omd init recommend처럼 존재하지 않는 CLI 서브커맨드를 호출하지 말 것"이라는 문장이 SKILL.md 본문에 그대로 적혀 있다(§9에서 다시 다룬다).

설계 패턴 ③ — 레퍼런스 토큰마다 "출처 앵커"를 달아 검증 가능하게 만든다

design-md/toss/DESIGN.md의 frontmatter를 열어보면 verification_v2.claims 블록에 YAML 앵커(&tds_button)와 참조(*tds_button)를 써서, tokens.colors.primary 같은 각 토큰 값이 어느 화면(surface)·어느 출처(source)·어떤 방법(computed-style-and-official-doc)·언제(captured 날짜) 확인됐는지 일일이 매핑해 둔다. "그냥 그럴듯한 값"이 아니라 "이 값은 이 URL의 이 방법으로 이 날짜에 확인했다"는 감사 추적(audit trail)이다.

설계 패턴 ④ — 채널마다 "받는 능력"을 의도적으로 차등한다

모든 채널이 같은 걸 받지 않는다. Claude Code는 스킬+18개 서브에이전트+훅+데이터 전체 번들을 받지만, Cursor는 규칙 파일 하나 + 공유 카탈로그만 받는다(서브에이전트·훅·스킬 없음). 이는 실수가 아니라 README가 명시한 설계 결정 — "Cursor는 omd:init 같은 스킬을 실행할 호스트가 아니다"라는 현실을 인정하고, Cursor 사용자에게는 미리 만든 DESIGN.md를 그대로 붙여 넣는 경로만 제공한다.

6기술 스택·의존성

버전 진실원(source of truth)부터 짚으면: 루트 package.json의 version은 1.9.0이고, CHANGELOG.md 최신 항목도 "1.9.0 — 2026-07-17"로 정확히 일치한다. 클론한 HEAD는 그보다 나흘 뒤인 0a7f3a1(2026-07-21) — 버전을 올리지 않은 문서/레퍼런스 후속 커밋으로 보인다.

① CLI — oh-my-design-cli (npm 배포 패키지)

② 웹앱 — web/ (oh-my-design.kr, 별도 미배포 패키지)

루트 CLI와 별개로, web/package.json(이름 web, 버전 0.1.0)이 정의하는 완전히 다른 Next.js 애플리케이션이 카탈로그 사이트·빌더·문서를 서빙한다.

③ 레거시 — packages/mcp/

과거 카탈로그를 MCP(Model Context Protocol) 서버로 서빙하던 구현이 남아 있다(server.ts·tools/get-design-md.ts·tools/search-by-vibe.ts 등). README가 명시적으로 "은퇴했고, 아카이브로만 남는다"고 밝힌다 — 지금 스킬들은 로컬 카탈로그 파일 또는 oh-my-design.kr/<id>/design.md raw 라우트를 직접 읽지, MCP 서버를 거치지 않는다.

7설치·요구사항

8실제 사용 흐름

9함정·오해 방지

10대안 비교

11정리 — 누가 쓰면 좋은가

기술적으로 이 레포에서 가장 배울 만한 것은 화려한 알고리즘이 아니라 "신뢰를 어떻게 파일 시스템 수준에서 기계적으로 보장하는가"다 — sha256 마커로 관리 파일과 사용자 수정본을 구분하고, YAML 앵커로 토큰 값마다 출처를 추적하고, 스킬 자신이 스스로의 오남용(존재하지 않는 CLI 호출)을 금지 문구로 막는 방식. "AI를 위한 문서 하나가 이 정도로 엄격하게 설계될 수 있다"는 사례로 읽으면 유익하다.

12직접 해볼 수 있는 실습 과제

아래 경로와 명령은 모두 레포 루트를 기준으로 합니다. 터미널 실습에는 rg(파일 내용 검색 도구)와 Node.js를 사용하며, 로컬 파일 읽기와 메모리 안의 값 비교로 진행합니다.

rg -n '^## |^### ' design-md/toss/DESIGN.md
cat design-md/toss/.verification.md

cat skills/omd-init/SKILL.md
rg -n '^## Phase|참고용|중단|찾지 못' skills/omd-init/SKILL.md

cat src/core/agent-detect.ts
cat test/unit/core/agent-detect.test.ts
cat skills/omd-sync/SKILL.md

node -e '
const { readFileSync } = require("node:fs");
const { createHash } = require("node:crypto");
const source = readFileSync(".claude/hooks/skill-activation.cjs", "utf8");
const raw = source.replace(/^\/\/ omd:installed-hook sha256=[0-9a-f]{64}\r?\n/m, "");
function hash(text) {
  return createHash("sha256").update(text).digest("hex");
}
const expected = hash(raw);
console.log("같은 본문:", expected === hash(raw));
console.log("공백 추가:", expected === hash(raw + " "));
'

13관련 기술 심화 학습 로드맵

매주 “개념을 자기 말로 설명하기 → 관련 소스 읽기 → 확인 가능한 결과물 만들기” 순서로 진행합니다. 테스트 파일은 입력과 기대 결과를 보여주는 예제집으로 읽고, 소스의 판단 근거를 함께 찾습니다.

마지막에는 “같은 설치를 반복해도 불필요한 변경이 없어야 한다”와 “사용자가 고친 내용을 구별해야 한다”는 요구를 각각 어떤 코드와 테스트가 맡는지 연결해 보세요. 이 연결표가 있으면 다른 설치기나 설정 동기화 도구도 같은 관점으로 읽을 수 있습니다.

14핵심 키워드 사전