impeccable로 프론트엔드 UI 디자인과 구현 안정성을 개선한 방법

2026. 7. 4.

impeccable로 프론트엔드 UI 디자인과 구현 안정성을 개선한 방법

서론

많은 팀이 UI를 만들 때 같은 문제를 겪습니다. 디자인 언어는 경험에 의존하고, 상호작용의 세부 사항은 기억에 의존하다 보니, 결과물이 “동작은 하지만 불안정한” 상태가 되기 쉽습니다.

HagiCode 모노레포에서 impeccable은 “영감을 주는 도구”로만 쓰지 않습니다. 실행 가능하고, 검증할 수 있고, 회귀를 확인할 수 있는 엔지니어링 흐름 안에 넣어서 사용합니다.

• 작업 진입점에 구조화된 제약이 있습니다(명령, 시나리오, 저장소 범위).
• 사이트 콘텐츠와 상위 명령 정의가 자동으로 맞춰집니다.
• 로컬 개발 포트, 실행 파라미터, 검증 절차가 고정되어 있습니다.

이 글은 저장소에 이미 구현된 내용을 바탕으로 Background, Analysis, Solution, Practice의 네 부분으로 나눠 설명합니다.

배경(Background)

현재 저장소 스냅샷에서 impeccable과 직접 관련된 핵심 위치는 세 곳입니다.

1. 정적 사이트 실행 오케스트레이션: scripts/static-sites-dev.mjs
2. impeccable 문서 사이트: repos/impeccable-site
3. UI task preset 계약 예시: designs/task-preset-plugin-examples/ui-master

이 중 세 번째는 설계 예시이며, 온라인 백엔드 런타임 코드 자체가 아닙니다. 이 점을 먼저 분명히 해야 “설계 계약”을 “배포된 동작”으로 오해하지 않습니다.

분석(Analysis)

1) 설계 의도를 먼저 구조화해서 “자유 해석”으로 인한 흔들림 줄이기

ui-master의 백엔드 계약 예시에서는 실행 전에 의존성과 입력을 먼저 고정합니다.

designs/task-preset-plugin-examples/ui-master/backend/task-preset.json:

{
  "taskKey": "uiMaster",
  "scriptKey": "autotask.ui-master",
  "requirements": [
    {
      "type": "skills",
      "name": "impeccable"
    },
    {
      "type": "cli",
      "name": "impeccable",
      "command": "npm",
      "args": ["exec", "--offline", "--", "impeccable", "--help"]
    }
  ],
  "inputBindings": [
    {
      "input": "uiMasterDescription",
      "promptParameter": "uiMasterDescription",
      "required": true
    },
    {
      "input": "uiMasterCommandIds",
      "promptParameter": "uiMasterCommandIds",
      "required": true
    },
    {
      "input": "sceneKey",
      "promptParameter": "sceneKey"
    }
  ]
}

핵심은 다음과 같습니다.

• skills:impeccable과 cli:impeccable을 먼저 검증해서, 실행 도중에야 체인이 끊긴다는 사실을 발견하지 않도록 합니다.
• uiMasterCommandIds로 명령 형태의 입력을 강제해서, “설명은 길지만 방향이 불분명한” 상황을 막습니다.
• sceneKey로 장면 키를 통일해서, 각 preset이 입력 이름을 제각각 만들지 않도록 합니다.

이 구조가 안정성에 주는 가치는 직접적입니다. 실패는 앞단에서 발생하고, 실패 원인은 설명 가능하며, 입력은 다시 재생할 수 있습니다.

2) 명령 목록과 문서 라우팅을 통일해서 의미 차이 줄이기

designs/task-preset-plugin-examples/ui-master/frontend/commands.json에는 명령 그룹, 문서 라우팅 템플릿, 명령 prelude가 정의되어 있습니다.

{
  "docs": {
    "baseUrl": "https://impeccable.hagicode.com",
    "routeTemplate": "/{lang}/docs/{commandId}",
    "languageResolver": "supported-language"
  },
  "commands": [
    {
      "id": "craft",
      "groupId": "build",
      "skill": "impeccable",
      "docsSlug": "craft",
      "preludeTemplate": "/impeccable {commandId} {uiMasterDescription}"
    }
  ]
}

실행 명령, 문서 설명, 언어 라우팅이 같은 ID 집합을 공유하므로 다음과 같은 어긋남을 줄일 수 있습니다.

• 문서에서는 A라고 부르는데 패널에서는 B라고 표시되는 문제
• 중국어 페이지가 잘못된 영어 명령으로 연결되는 문제
• prompt prelude와 docs slug가 일치하지 않는 문제

3) 사이트 구현에서 “콘텐츠 정확성”을 검증 가능한 자산으로 만들기

repos/impeccable-site/package.json에서는 validate가 전체 품질 게이트를 연결합니다.

{
  "scripts": {
    "validate": "npm run i18n:check && npm run catalog:check && npm run typecheck && npm run test && npm run build"
  }
}

또한 catalog:check 뒤의 스크립트(scripts/build-command-catalog.mjs)는 frontmatter 구조에 대해 강한 검사를 수행합니다.

function parseFrontmatter(sourceText, sourcePath) {
  const match = sourceText.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/u);
  assert(match, `${sourcePath} must include YAML frontmatter`);
  const frontmatter = load(match[1]);
  assert(isPlainObject(frontmatter), `${sourcePath} frontmatter must be a mapping`);
  return {
    frontmatter,
    body: match[2].trim(),
  };
}

이런 assert는 단순하지만 안정성에 매우 중요합니다. 문서 필드가 빠진 사실을 배포 후에 알아차리는 것보다, 로컬과 CI에서 바로 실패하는 편이 낫습니다.

4) 개발 환경의 포트와 env를 고정해서 “내 환경에서는 되는데 네 환경에서는 안 되는” 상황 막기

모노레포 루트 스크립트 scripts/static-sites-dev.mjs에는 impeccable이 명시적으로 오케스트레이션되어 있습니다.

{
  id: 'impeccable',
  name: 'Impeccable',
  repoPath: 'repos/impeccable-site',
  productionUrl: 'https://impeccable.hagicode.com/',
  command: 'npm',
  args: ['run', 'dev'],
  env: {
    PORT_IMPECCABLE_SITE: '36296'
  },
  portHint: 36296,
  order: 56
}

scripts/static-sites-dev.test.mjs도 포트, args, env, productionUrl 같은 값을 테스트로 검증합니다.

이런 “고정 값 + 테스트” 방식은 화려하지 않지만 안정적입니다.

• 로컬 진입점이 통일됩니다.
• 문제 해결 경로가 고정됩니다.
• 문서 사이트 링크가 임의로 바뀌지 않습니다.

해결(Solution)

impeccable로 UI 품질과 구현 안정성을 함께 높이려면, 현재 저장소의 실천 방식을 기준으로 네 개의 계층으로 정리할 수 있습니다.

1계층: 작업 진입점의 계약화

방법: ui-master 같은 preset 구조를 재사용합니다.

목표:

• 허용되는 저장소 범위를 제한합니다(targetRepositories).
• 명령의 출처를 제한합니다(uiMasterCommandIds).
• 컨텍스트 진입점을 제한합니다(uiMasterDescription).

효과: 매번 “입력이 무엇이었고, 왜 이렇게 바꿨는지”를 다시 검토할 수 있습니다.

2계층: 명령 의미의 통일

방법: 명령 ID, docs slug, prelude template을 하나로 묶어 관리합니다.

목표:

• 패널에서 선택한 명령이 같은 ID의 문서로 이동하도록 합니다.
• prompt의 /impeccable <command>와 문서 설명이 일치하도록 합니다.

효과: “용어는 같은데 동작은 다른” 숨은 위험을 줄입니다.

3계층: 콘텐츠 자산의 검증 자동화

방법: npm run validate를 커밋 전 게이트로 유지합니다.

목표:

• i18n 키가 누락되지 않도록 합니다.
• 명령 목록과 상위 구조가 어긋나지 않도록 합니다.
• 타입 검사, 테스트, 빌드가 한 번에 통과하도록 합니다.

효과: 간헐적으로 발생하는 콘텐츠 문제를 로컬 단계에서 미리 찾아냅니다.

4계층: 개발 실행 환경의 표준화

방법: static-sites-dev로 일괄 실행하고, PORT_IMPECCABLE_SITE를 고정합니다.

목표:

• 여러 사람이 협업할 때 포트 충돌을 최소화합니다.
• 여러 사이트를 함께 연동할 때 경로를 고정합니다.

효과: 환경을 맞추는 시간을 줄이고, 문제를 코드 자체로 더 빨리 좁힐 수 있습니다.

실천(Practice)

Step 1: impeccable-site 초기화

cd /home/newbe36524/repos/hagicode-mono/repos/impeccable-site
git submodule update --init --recursive
env -u NPM_CONFIG_PREFIX npm install

Step 2: 로컬 개발과 전체 검증

env -u NPM_CONFIG_PREFIX npm run dev
env -u NPM_CONFIG_PREFIX npm run validate

validate는 i18n, catalog, typecheck, test, build를 한 번에 모두 실행합니다.

Step 3: 모노레포 통합 오케스트레이션에서 실행

모노레포 루트에서 scripts/static-sites-dev.mjs 체계를 따라 실행하고, 이미 정의된 PORT_IMPECCABLE_SITE=36296을 그대로 사용합니다.

이 단계의 핵심은 “실행만 되는 것”이 아니라 “모두가 같은 방식으로 실행하는 것”입니다.

Step 4: UI 요청을 명령형 입력으로 변환

task preset 흐름에서는 요구사항을 먼저 다음 형태로 정리하는 것을 우선합니다.

• uiMasterDescription: 비즈니스 목표
• uiMasterCommandIds: 이번 작업의 명령(예: craft, audit, polish)
• sceneKey: 장면 컨텍스트

그다음 변경 단계로 들어가면, UI를 바로 고치면서 방향이 틀어지는 일을 줄일 수 있습니다.

Step 5: 현재 자료의 공백 명확히 하기

현재 저장소 스냅샷에서 확인할 수 있는 내용은 다음과 같습니다.

• impeccable-site의 사이트와 검증 흐름은 실제 구현된 코드입니다.
• ui-master와 impeccable의 깊은 연동 계약은 주로 designs/task-preset-plugin-examples와 설계 문서에 나타납니다.

“프로덕션 백엔드에서 전면 활성화되었다”는 결론을 내리려면 지금의 근거로는 부족합니다. 그런 판단은 아직 보류하는 편이 좋습니다.

HagiCode 정보 소개

HagiCode는 멀티 저장소 엔지니어링, AI 작업 실행, 문서 사이트, 도구 체인을 하나로 묶은 플랫폼형 프로젝트입니다. 핵심 가치는 단순히 “코드를 생성할 수 있다”는 데 있지 않고, 작업 입력의 제약, 실행 컨텍스트, 검증 게이트, 저장소 간 협업을 하나의 안정적인 파이프라인으로 연결하는 데 있습니다. 대표적인 사용 시나리오는 구조화된 UI 반복 개선, 여러 저장소에 걸친 기능 연동, 규격 기반 기술 콘텐츠 제작, 품질 게이트가 있는 자동화 배포입니다.

요약

impeccable의 진짜 가치는 “더 예쁜 버튼을 제안해 주는 것”이 아니라, “UI 최적화를 엔지니어링으로 만드는 것”에 있습니다. HagiCode의 현재 실천에서는 이를 네 가지 동작으로 실현합니다. 작업 계약화, 명령 의미 통일, 콘텐츠 검증 선행, 실행 환경 표준화입니다. 이 기반을 먼저 탄탄하게 다져 두면, 그 위에 더 화려한 디자인 개선을 얹어도 효과가 더 크고 오래갑니다.

Tags:

• impeccable
• frontend
• stability
• hagicode

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