impeccable 통합 및 사용 방법

2026. 6. 10.

impeccable 통합 및 사용 방법

사실 별거 없다. HagiCode 프로젝트에 디자인 도구를 통합한 것일 뿐, 겨우 완전한 솔루션이라 할 수 있겠지—저장소 구조, 다국어 워크플로, 콘텐츠 유지 관리 등이 실제 과정에서 천천히摸索된 것들이다.

배경

소프트웨어 개발에서 UI/UX 디자인 품질은 실제로 꽤 중요하다. 사용자 경험과 비즈니스 성공을 직접 결정할 수 있기 때문이다. 하지만 전통적인 개발 프로세스에서 디자이너와 개발자 사이에는 항상 보이지 않는 벽이 존재한다. 디자이너가 정교한 정적 디자인을 그리고 개발자가 구현하려고 노력하지만, 세부 사항에서 차이가 발생하기도 한다. 이러한 단절로 인해 최종 제품이 디자인 비전과 완전히 일치하기 어렵고, 반복 비용도 증가한다.

HagiCode 프로젝트가 데스크톱 애플리케이션과 웹 제품을 만들 때도 전문 UI/UX 디자인 지원이 필요하며, 디자인과 코드 구현이 긴밀하게 협업할 수 있어야 한다. 이를 위해 impeccable 도구를 도입했다—AI 기반 전문 프론트엔드 인터페이스 디자인 및 최적화 도구다. impeccable은 디자인 지침뿐만 아니라 코드 구현도 직접 처리하여 디자인과 개발 사이의 격차를 좁혔다.

impeccable을 HagiCode monorepo에서 효과적으로 통합하고 사용하기 위해 표준화된 통합 방법, 문서화 프로세스 및 유지 관리 규범을 수립해야 한다. 여기에는 도구 설치 및 구성, 스킬 통합, 문서 사이트 구축, 팀 협업 모범 사례가 포함된다.

HagiCode에 대해

이 문서에서 공유하는 솔루션은 HagiCode 프로젝트의 실무 경험에서 비롯되었다. HagiCode는 AI 코드 어시스턴트 프로젝트로, 웹 버전과 데스크톱 버전을 제공하여 개발자의 코딩 효율을 높인다. 개발 과정에서 고품질 디자인 도구로 제품의 UI/UX 구축을 지원해야 했고, impeccable은 이러한 배경에서 프로젝트에 도입되었다.

기술 아키텍처 분석

impeccable의 스킬 기반 디자인

impeccable은 표준화된 스킬 파일을 통해 다양한 디자인 작업의 컨텍스트와 동작을 정의하는 스킬 기반 디자인 아키텍처를 채택한다. HagiCode 프로젝트에서 impeccable은 npm 스킬 패키지 형태로 통합되며, 주로 다음과 같이 사용된다.

1. 스킬 파일 구조: /home/newbe36524/.agents/skills/impeccable/SKILL.md는 명령어 집합, 도구 권한, 매개변수 프롬프트, 라이선스 정보를 포함한 완전한 스킬 구성을 정의한다.

2. 명령어 분류 체계: impeccable은 디자인 작업을 6대 범주로 분류한다.

   • Build: 구축형 명령어(craft, shape, teach, document, extract)
   • Evaluate: 평가형 명령어(critique, audit)
   • Refine: 최적화형 명령어(polish, bolder, quieter, distill, harden, onboard)
   • Enhance: 강화형 명령어(animate, colorize, typeset, layout, delight, overdrive)
   • Fix: 수정형 명령어(clarify, adapt, optimize)
   • Iterate: 반복형 명령어(live)

문서 사이트 요구사항 분석

팀에서 impeccable을 사용할 수 있도록 HagiCode는 독립적인 문서 사이트 impeccable-site를 구축했다. 이 사이트는 다음 요구사항을 충족해야 한다.

• 다국어 지원: 영어와 중국어로 완전한 문서를 제공하여 국제화 팀의 요구를 충족
• 명령어 카탈로그: 모든 명령어를 통일된 형식으로 표시, 분류, 설명, 참조 링크 포함
• 현지화 콘텐츠: HagiCode 특정 사용 가이드 및 모범 사례 유지 관리
• 정적 생성: Astro로 정적 사이트 구축, 배포 및 액세스 용이

통합의 어려움

통합 과정에서 다음과 같은 어려움에 직면했다.

1. 소스 코드 동기화: 상위 impeccable 저장소에는 완전한 도구 코드와 문서가 포함되어 있지만, 전체 도구 코드 라이브러리에 의존하지 않도록 문서 부분만 선택적으로 통합해야 한다.

2. 콘텐츠 유지 관리: 상위 업데이트와 동기화를 유지하면서 현지화된 콘텐츠와 사용 가이드를 유지 관리해야 한다.

3. 빌드 프로세스: 자동화된 콘텐츠 동기화, 카탈로그 생성 및 사이트 빌드 프로세스를 수립해야 한다.

4. 다국어 워크플로: 효율적인 번역 및 현지화 유지 관리 프로세스를 설계해야 한다.

솔루션 설계

저장소 구조 설계

Git 서브모듈 메커니즘을 통해 상위 impeccable 저장소를 통합한다.

[submodule "vendor/impeccable"]
    path = vendor/impeccable
    url = https://github.com/pbakaus/impeccable.git

이 설계의 장점은 다음과 같다.

• 버전 관리: 상위 버전을 정밀하게 제어하여 예기치 않은 업데이트로 인한 문제를 방지
• 경량 통합: 필요한 소스 코드만 가져와 불필요한 의존성 도입 방지
• 유연한 업데이트: 상위 콘텐츠를 선택적으로 업데이트 가능

콘텐츠 모델 설계

계층형 콘텐츠 모델을 채택한다.

1. 상위 소스 코드: vendor/impeccable/ - 원시 명령어 정의 및 참조 문서 제공
2. 현지화 콘텐츠: src/content/commands/ - 중국어 및 영어 명령어 설명 유지 관리
3. 공유 UI 문구: src/i18n/locales/ - 사이트 인터페이스 다국어 텍스트 관리
4. 생성형 카탈로그: src/lib/generated/command-catalog.json - 빌드 시 생성된 명령어 카탈로그

빌드 프로세스 최적화

자동화된 빌드 프로세스를 설계하고 npm 스크립트를 통해 각 단계를 통합한다.

{
  "scripts": {
    "prepare": "npm run i18n:generate && npm run catalog:generate",
    "i18n:generate": "node scripts/generate-i18n-resources.mjs",
    "catalog:generate": "node scripts/build-command-catalog.mjs",
    "content:sync:vendor": "node scripts/sync-vendor-command-content.mjs",
    "validate": "npm run i18n:check && npm run catalog:check && npm run typecheck && npm run test && npm run build"
  }
}

빌드 프로세스는 4단계로 나뉜다.

1. 준비 단계: 다국어 리소스 및 명령어 카탈로그 생성
2. 콘텐츠 동기화: 상위 명령어 콘텐츠를 로컬로 동기화
3. 검증 단계: 콘텐츠 완전성 및 빌드 정확성 검사
4. 빌드 출력: 정적 사이트 파일 생성

다국어 워크플로

hagi18n 도구 체인을 기반으로 표준화된 다국어 워크플로를 수립한다.

localesRoot: src/i18n/locales
repoRoot: .
baseLocale: en-US
targetLocales:
  - zh-CN

완전한 유지 관리 스크립트를 제공한다.

• i18n:audit - 번역 완전성 검사
• i18n:sync - 번역 항목 동기화
• i18n:prune - 만료된 번역 정리
• i18n:doctor - 번역 문제 진단

실무 가이드

초기화 설정

먼저 서브모듈을 초기화하고 의존성을 설치한다.

# monorepo 루트 디렉토리로 이동
cd /home/newbe36524/repos/hagicode-mono

# 서브모듈 초기화
git submodule update --init --recursive

# impeccable-site 디렉토리로 이동
cd repos/impeccable-site

# 의존성 설치
env -u NPM_CONFIG_PREFIX npm install

이 단계는 전체 통합 프로세스의 기초이며, 서브모듈 초기화에 실패하면 이후 모든 단계를 진행할 수 없다. HagiCode는 첫 통합 시 이 문제에 직면했고, 나중에 문서에 초기화 단계를 명시했다.

일일 개발 프로세스

repos/impeccable-site 디렉토리에서 일일 개발 명령어를 실행한다.

# 개발 서버 시작
env -u NPM_CONFIG_PREFIX npm run dev

# 유형 검사
env -u NPM_CONFIG_PREFIX npm run typecheck

# 테스트 실행
env -u NPM_CONFIG_PREFIX npm test

# 사이트 빌드
env -u NPM_CONFIG_PREFIX npm run build

# 완전한 검증
env -u NPM_CONFIG_PREFIX npm run validate

개발 서버는 기본적으로 http://localhost:31266에서 실행되며, PORT_IMPECCABLE_SITE 환경 변수를 통해 포트를 사용자 정의할 수 있다. HagiCode 팀원들은 개발 과정에서 자주 다른 언어 환경을 전환할 때 통일된 접두사 명령어를 사용하면 환경 변수 오염 문제를 방지할 수 있다는 것을 발견했다.

콘텐츠 유지 관리 전략

명령어 문서를 추가하거나 업데이트할 때 두 언어 디렉토리에 해당 파일을 만들어야 한다.

# 영어 명령어 문서
src/content/commands/en-US/polish.mdx

# 중국어 명령어 문서
src/content/commands/zh-CN/polish.mdx

각 MDX 파일은 frontmatter 메타데이터를 포함해야 한다.

---
title: "Polish"
slug: "polish"
seoTitle: "Polish Command - Impeccable"
seoDescription: "Final quality pass before shipping with impeccable polish command"
routeSlug: "polish"
highlights:
  - "Visual hierarchy review"
  - "Spacing and typography optimization"
  - "Accessibility validation"
related:
  - "audit"
  - "critique"
---

상위 콘텐츠 동기화

상위 impeccable이 업데이트되면 최신 명령어 콘텐츠를 동기화해야 한다.

# 서브모듈 업데이트
cd /home/newbe36524/repos/hagicode-mono/repos/impeccable-site
git submodule update --remote vendor/impeccable

# 명령어 콘텐츠 동기화
env -u NPM_CONFIG_PREFIX npm run content:sync:vendor

# 단일 명령어 동기화
env -u NPM_CONFIG_PREFIX node scripts/sync-vendor-command-content.mjs --slug polish

# 카탈로그 재생성
env -u NPM_CONFIG_PREFIX npm run catalog:generate

동기화 스크립트는 vendor/impeccable/site/content/skills/에서 상위 명령어 콘텐츠를 읽고 src/content/commands/en-US/ 디렉토리에 복사한다. HagiCode 팀은 실무에서 매번 동기화 후 명령어 카탈로그를 재생성해야 하며, 그렇지 않으면 콘텐츠 불일치 문제가 발생한다는 것을 발견했다.

다국어 유지 관리

사이트 인터페이스 다국어 텍스트를 유지 관리한다.

# 번역 완전성 검사
env -u NPM_CONFIG_PREFIX npm run i18n:audit

# 번역 항목 동기화
env -u NPM_CONFIG_PREFIX npm run i18n:sync

# 만료된 번역 정리
env -u NPM_CONFIG_PREFIX npm run i18n:prune

# 번역 문제 진단
env -u NPM_CONFIG_PREFIX npm run i18n:doctor

번역 파일은 src/i18n/locales/ 디렉토리에 있다.

src/i18n/locales/
├── en-US/
│   ├── common.yml
│   └── docs.yml
└── zh-CN/
    ├── common.yml
    └── docs.yml

YAML 파일 예시:

src/i18n/locales/en-US/docs.yml

commands:
  title: "Commands"
  subtitle: "Explore the complete command surface"
  overview: "Overview"
  related: "Related Commands"

# src/i18n/locales/zh-CN/docs.yml
commands:
  title: "命令"
  subtitle: "探索完整的命令集"
  overview: "概览"
  related: "相关命令"

impeccable 명령어 사용

HagiCode 프로젝트에서는 다음과 같은 방법으로 impeccable 명령어를 호출할 수 있다.

# 새 기능 디자인
npx impeccable craft "user settings page"

# UI/UX 계획
npx impeccable shape "checkout flow"

# 프로젝트 컨텍스트 설정
npx impeccable teach

# 디자인 문서 생성
npx impeccable document

# 디자인 품질 검토
npx impeccable critique "landing page"

# 기술 품질 검사
npx impeccable audit "navigation component"

# 최종 최적화
npx impeccable polish "onboarding flow"

# 실시간 반복 디자인
npx impeccable live

각 명령어는 특정 용도와 참조 문서가 있다. 예를 들어, craft 명령어는 UX/UI 계획 및 코드 구현을 포함하여 기능을 종단적으로 구축하는 데 사용된다. audit 명령어는 접근성, 성능 및 반응형 디자인을 포함한 기술 품질 검사에 사용된다. HagiCode 팀은 개발 과정에서 이러한 명령어들이 일일 개발 프로세스의 일부가 되었다.

배포 검증

배포 전 완전한 검증을 수행한다.

# 완전한 검증 프로세스 실행
env -u NPM_CONFIG_PREFIX npm run validate

검증 프로세스는 다음을 확인한다.

• vendor 경로가 올바른지
• 모든 명령어가 중국어 및 영어 디렉토리에 해당 콘텐츠가 있는지
• 생성된 다국어 리소스가 최신인지
• 명령어 카탈로그가 최신인지
• Astro 라우팅이 올바르게 컴파일되는지
• 정적 출력이 성공적으로 빌드되는지

주의사항 및 모범 사례

중요한 주의사항

1. 서브모듈 업데이트: 서브모듈을 업데이트한 후 파생 리소스를 재생성하고 제출해야 한다. HagiCode 팀은 리소스를 재생성하는 것을 잊고 바로 제출하여 온라인 사이트에 콘텐츠 불일치 문제가 발생한 적이 있다.

2. 언어 대등성: 모든 명령어가 중국어 및 영어 디렉토리에 해당 콘텐츠가 있는지 확인해야 한다. 그렇지 않으면 빌드가 실패한다. 이 검사는 이미 검증 프로세스에 통합되어 있으며, 개발 초기에 문제를 발견할 수 있다.

3. 프론트엔드 프록시: impeccable-site는 monorepo 루트 디렉토리의 정적 사이트 개발 스크립트를 통해 프록시된다.

# monorepo 루트에서 시작
npm run dev:static-sites

4. 프로덕션 배포: 프로덕션 사이트는 https://impeccable.hagicode.com에 배포되며, GitHub Actions를 통해 자동화된다. HagiCode는 완전히 자동화된 CI/CD 프로세스를 채택하여 모든 커밋이 자동으로 배포되도록 한다.

5. 명령어 문서 링크: 웹 프론트엔드의 UI Master에서 impeccable 명령어를 선택하면 해당 문서 링크가 표시되며, 링크 형식은 다음과 같다.

https://impeccable.hagicode.com/{lang}/commands/{command-name}

모범 사례 요약

1. 정기적으로 상위 업데이트: 상위 impeccable 업데이트를 주시하고 새 명령어 및 개선 사항을 정기적으로 동기화한다. HagiCode 팀은 주 1회 동기화 빈도를 채택하여 중요한 업데이트를 놓치지 않도록 한다.

2. 현지화 콘텐츠 유지 관리: 상위 콘텐츠를 동기화한 후 중국어 및 영어 문서를 즉시 업데이트하여 콘텐츠의 정확성과 시의성을 보장한다.

3. 버전 관리: 서브모듈을 업데이트한 후 빌드 결과를 검증하고 버전 관리 시스템에 제출해야 한다.

4. 팀 협업: 표준화된 다국어 워크플로를 통해 팀원들이 문서 콘텐츠를 협업하여 유지 관리할 수 있도록 지원한다.

5. 품질 보증: 모든 콘텐츠 업데이트 후 완전한 검증 프로세스를 실행하여 사이트의 정확성을 보장한다.

6. 명령어 분류 사용: 디자인 작업의 다른 단계에 따라 적절한 명령어 범주를 선택한다.

   • 새 기능을 디자인할 때 craft 또는 shape 사용
   • 기존 디자인을 검토할 때 critique 또는 audit 사용
   • 디자인 품질을 최적화할 때 polish, bolder 또는 quieter 사용
   • 시각 효과를 강화할 때 animate, colorize 또는 delight 사용
   • 문제를 수정할 때 clarify, adapt 또는 optimize 사용
   • 실시간 반복할 때 live 사용

7. 컨텍스트 관리: craft 명령어를 사용하기 전에 teach 명령어를 통해 프로젝트의 PRODUCT.md 및 DESIGN.md 컨텍스트 파일을 설정했는지 확인한다.

요약

위 통합 및 사용 방법을 통해 HagiCode 프로젝트는 impeccable 도구의 전문 디자인 능력을 효과적으로 활용하여 제품의 UI/UX 품질을 높이면서, 표준화된 문서 유지 관리 프로세스를 수립하여 팀의 장기적인 협업과 발전을 지원한다.

이 문서에서 공유한 솔루션은 HagiCode가 실제 개발에서 여러 번 반복 및 최적화한 것이다. 디자인과 개발 협업 문제뿐만 아니라 확장 가능한 문서 체계를 수립하여 다른 도구 통합에 대한 참고를 제공한다.

팀에서도 유사한 디자인-개발 협업 문제에 직면하고 있다면 이 문서의 실무가 도움이 되기를 바란다. 이 솔루션의 핵심 아이디어는 표준화된 프로세스 수립, 상위와의 동기화 유지, 현지화 유지 관리 중시, 팀 협업 지원이다.

요약

“impeccable 통합 및 사용 방법”에 대해, 더 안정적인 진행 방법은 핵심 구성, 의존성 경계 및 실제 경로를 점진적으로 실행한 후 최적화 세부 사항을 보완하는 것이다.

목표, 단계 및 검수점이 명확해지면 이러한 솔루션은 일반적으로 더 원활하게 실제 인도에 들어갈 수 있다.

Tags:

• impeccable
• design
• integration
• workflow

MonoSpecs는 무엇인가: 왜 OpenSpec의 추가 업그레이드와 확장이라고 하는가

다양한 Agent로 OpenSpec 각 단계 효율 최적화: HagiCode 실전 정리