DESIGN.md를 써보고 싶었을 뿐인데 블로그를 마이그레이션 한 사연

VoltAgent에서 발견한 DESIGN.md

VoltAgent에는 AI 에이전트 관련 자료를 모아둔 저장소들이 있다. awesome-agent-skills, awesome-claude-code-subagents, awesome-codex-subagents처럼 Claude Code, Codex, Gemini CLI에서 쓸 수 있는 skill이나 subagent를 정리한 저장소들이다.

나 역시 해당 저장소들의 subagents들을 부려가며 개발에 적극 활용하고 있는데, 그 저장소들 사이에 awesome-design-md라는 저장소가 있다. star가 제일 많이 찍힌 저장소다. 인기 있는 브랜드 디자인 시스템을 DESIGN.md 형태로 분석해 모아둔 저장소인데, 이걸 알게 됐을 때 바로 생각했다.

“이건 꼭 써보리라..!!”

DESIGN.md를 쓰고 싶어서 몸이 간질간질해진 나머지 블로그를 이사한 사연을 짧은 시리즈로 풀어보려고 한다.

DESIGN.md란?

DESIGN.md는 쉽게 말해 이 프로젝트가 어떤 얼굴을 가져야 하는지 규칙을 문서화한 것이다. 코드에 AGENTS.md나 CLAUDE.md 같은 작업 지침이 있다면, 화면에는 DESIGN.md 같은 디자인 지침을 둘 수 있지 않을까 하는 발상에서 시작됐다.

안에 들어 있는 것들

저장소의 설명에 따르면 좋은 DESIGN.md에는 대충 이런 것들이 들어간다.

• 이 서비스의 전체 분위기는 차분한지, 화려한지, 밀도가 높은지.
• 색상은 어떤 이름으로 부르고 어디에 쓰는지.
• 제목, 본문, 코드, 캡션의 타이포그래피는 어떻게 나뉘는지.
• 버튼, 카드, 인풋, 내비게이션은 기본 상태와 hover/focus 상태에서 어떻게 보여야 하는지.
• 여백은 어느 단위로 쌓고, grid는 어떻게 쓰고, shadow는 어느 정도까지 허용할지.
• 그리고 하지 말아야 할 것도 같이 적는다. 예를 들면 “이 브랜드에서 과한 gradient는 쓰지 말 것”, “CTA는 이 색상 하나만 쓸 것” 같은 가드레일이다.

게다가 마지막에 agent prompt guide까지 들어간다. 사람이 읽는 디자인 문서에서 끝나는 게 아니라, 에이전트에게 바로 던질 수 있는 색상 참고, 컴포넌트 규칙, 프롬프트 힌트까지 같이 들어간다. 디자인 문서이면서 동시에 프롬프트 재료인 셈이다.

각 사이트 폴더에는 색상 swatch, type scale, 버튼, 카드 같은 걸 눈으로 확인할 수 있는 preview.html과 dark surface용 preview-dark.html도 같이 있다. 문서만 보고 상상하는 게 아니라, 이 디자인 언어가 실제 화면에서 어떤 느낌인지 먼저 훑어볼 수 있게 해둔 것이다.

설치는 그냥 복사 한 번

설치 방법은 허무할 정도로 단순하다. 원하는 사이트의 DESIGN.md를 골라서 프로젝트 루트에 복사한다. 그리고 Codex나 Claude에게 “이 프로젝트의 디자인 기준은 DESIGN.md야. 새 화면을 만들 때 이 문서를 먼저 읽고 맞춰줘”라고 말하면 된다. 그냥 markdown 파일 하나를 넣고, 에이전트가 그 문서를 기준으로 UI를 만들게 하는 방식이다.

아, 디자인 감각도 문서로 남겨둘 수 있다니!!

공식 지원 문서는 아니다

다만 DESIGN.md는 AGENTS.md나 CLAUDE.md처럼 도구가 공식적으로 읽어주는 문서는 아니다. AGENTS.md는 AI 코딩 에이전트에게 프로젝트 지침을 주기 위한 포맷이고, Claude Code는 CLAUDE.md를 세션 시작 시 읽는 프로젝트 메모리로 다룬다. 반면 DESIGN.md는 아직 그런 자동 계약이 없다. 저장소 안에 같이 두고, Codex나 Claude에게 “이 문서를 디자인 기준으로 참고해줘”라고 명시해서 쓰는 문서다.

코드를 어떻게 짤지 합의하는 문서가 있듯이, 화면을 어떻게 만들지 합의하는 문서다. 특히 AI와 함께 UI를 만들 때는 이 차이가 꽤 크다. “예쁘게 만들어줘”는 매번 다른 결과를 부르지만, “이 색상 토큰과 컴포넌트 규칙과 밀도를 따라줘”는 결과의 비결정성을 줄여준다.

AI에게 디자인 감성을 맡기면 생기는 문제

회사에서 Next.js로 어드민을 구축하면서 FE, UI 작업까지 Codex를 활용했는데, 다른 건 다 그렇다치고 불만이었던 점은 디자인이었다.

정확히 말하면 못생겼다기보다 비결정적이었다. 어떤 화면은 카드 간격이 넓고, 어떤 화면은 버튼이 과하게 둥글고, 글씨 크기도 들쭉날쭉하고, 어떤 화면은 SaaS 대시보드 같다가 또 어떤 화면은 블로그 같이 보였다.

한 번의 프롬프트 안에서는 그럴듯한데, 여러 번 작업을 이어가면 디자인 감성이 조금씩 달랐다. 마치 수십 명의 디자이너가 각자 다른 스타일로 화면을 만드는 것 같달까…

그때 든 생각이 이거였다.

AI에게 어떻게 “디자인 감성”을 일관되게 유지시키지?

그 문제를 해결할 수 있는 게 DESIGN.md처럼 보였다. 디자인 감각 부족의 한계를 느끼던 나같은 개발자에게 너무 고마운 도구이지 않은가!

회사 어드민에서 먼저 써봤다

그래서 실제로 앞서 말한 Next.js 어드민 프로젝트에 Linear – The system for product development 스타일 DESIGN.md를 적용해봤다.

프롬프트도 심플하게 “이 프로젝트의 디자인 기준은 DESIGN.md야. 기존 화면을 이 문서에 따라 리디자인 해줘”라고만 했다. 그리고 Codex가 만들어주는 UI가 그 규칙을 따르는지, 그리고 결과물이 일관된 스타일로 나오는지 지켜봤다.

결과는 만족스러웠다. 일관성 없게 지저분해보이던 UI가 훨씬 일관되고 안정적인 Linear 감성으로 정리됐다.

희열(?)을 맛본 나는 몸이 근질근질해졌다. 회사 프로젝트에서 효과를 봤으니, 이제 또 다른 프로젝트에도 써보고 싶었다. 유명 사이트들의 디자인 시스템을 차용하고 써먹고 싶었다.

그 적용 대상으로 제일 먼저 떠오른 게 방치되어 있던 나의 Tistory 블로그였다.

그러다 방치된 블로그가 떠올랐다

사실 개발자로 본격적으로 일하기 전 GitHub Pages 기반으로 정적 블로그를 만드려는 시도는 해봤으나, 그때는 AI 도구도 없었으니, 괜찮은 템플릿 받아다가 요리조리 커스텀하고 해야 했다. 그런데 그렇게 들이는 비용에 비해 얻을 수 있는 이득이 그다지 커보이지 않아서 그냥 기존 플랫폼에 얹혀가야겠다고 포기했던 기억이 있다.

하지만 지금 나에게는 Codex와 Claude라는 강력한 동반자들이 있고, DESIGN.md라는 문서도 있다. 이걸 활용해서 블로그를 새로 만들어보면 어떨까?라는 생각이 들었다.

사실 근데 내 블로그가 떠오른 이유가 단지 디자인 실험 때문만은 아니었다. 더 오래 묵은 이유가 있었다.

오래 묵은 노트들

아는 분들은 다 아시겠지만 에버노트라는 훌륭한 노트 테이킹 도구가 있었다. 나도 한 때는 에버노트를 활용하던 시절이 있었다. 그러다가 조플린이라는 오픈소스 앱으로 갈아탔고, 지금은 옵시디언을 쓰고 있다.

5, 6년 정도는 계속 디지털 다이어리를 써온 것 같다. 그중 옵시디언만 해도 4, 5년은 쓴 듯 하다. 온갖 것들이 전부 옵시디언 안에 쌓여 있다.

그래서 늘 하나의 숙제와도 같았다. 이 노트들을 어떻게 다듬어서 세상에 내보낼까…

티스토리를 쓸 때는 옵시디언에 “티스토리 발행 플러그인”이 있었다. 옵시디언에서 글을 쓰고, 티스토리로 발행하기 기능을 사용하면 내 로컬 옵시디언 마크다운 노트를 Tistory와 거의 동기화하듯이 쓸 수 있었다. 글을 쓰는 공간과 발행하는 공간이 완전히 분리되지 않으니 편했다고 할 수 있다.

그런데 Tistory가 Open API를 닫으면서 플러그인을 사용할 수 없게 되었고, 자연스럽게 블로그에 대한 관심도 줄어들었다. 한 2년 정도는 블로그를 거의 방치했다.

결론: 블로그를 직접 만들자

그래서 결국 다음과 같은 결론에 도달했다:

DESIGN.md를 적용하기 위해 내 블로그를 직접 만들자!!

그 결과물이 바로 이곳이다. 실제로 이 블로그에 어울리는 디자인 방향을 고르는 일도 Codex에게 시켰다. 여러 레퍼런스 중에서 뭘 따라가면 좋겠냐고 물었고, Codex가 제안한 여러 선택지 중에 나는 Mintlify - The Intelligent Knowledge Platform를 골랐다. 문서형 제품, 차분한 민트색, 콘텐츠를 앞세우면서도, 개발자 도구 느낌이 있다.

실제로 Mintlify DESIGN.md의 overview와 key characteristics를 보면 이런 식으로 설명되어 있다.

Mintlify positions itself at the intersection of polished marketing presentation and developer-grade documentation density. The home and startups pages open with cinematic atmospheric heroes — soft sky-gradient backdrops with cloud illustrations on the homepage, dark teal-to-mint gradients with a rocket launch on the startups page — that feel more like a SaaS landing aesthetic than a developer tool.

The brand’s signature mint green ({colors.brand-green}) appears sparingly but decisively — on the hero “Get started” pill button, the green checkmark icons inside feature lists, the “Featured” pricing tier border, and active state indicators inside docs UI.

Key Characteristics: Atmospheric gradient hero bands, signature Mintlify mint green for accents, black-pill primary buttons, Inter for UI prose, Geist Mono for code, dense 3-column documentation layouts, and tightly-controlled radius scale.

요약하면:

• 마케팅 페이지처럼 시원하게 열리지만, 실제 콘텐츠 영역은 문서형 제품처럼 촘촘함.
• 민트색을 여기저기 뿌리지 않고, CTA와 active state 같은 중요한 순간에만 씀.
• 검은 pill 버튼, 낮은 radius, 충분한 여백으로 만드는 차분한 개발자 도구 느낌.
• Inter와 Geist Mono 조합에서 오는 문서/코드 친화적인 인상. (→ 다만 이 부분은 한글 fallback 폰트로 보완이 필요했다.)

여기까지가 “왜 다시 블로그를 만들게 됐는가”에 대한 이야기다. 다음 글에서는 실제로 어떤 스택을 골랐고, AI 티(?)를 어떻게 덜어내려고 노력했는지, 이전 글은 어떤 기준으로 옮겼는지, 댓글과 배포와 도메인은 어떻게 결정했는지 등을 정리해보려고 한다.