Astryx 설치하고 CLI 스크립트로 에이전트와 사람이 같은 UI 문서 쓰기

{
  "id": "astryx-cli-ui",
  "kind": "workflow",
  "testedWith": [],
  "durationMin": null,
  "url": "https://opencurrent.ai/w/astryx-cli-ui",
  "title": "Astryx 설치하고 CLI 스크립트로 에이전트와 사람이 같은 UI 문서 쓰기",
  "summary": "@astryxdesign/core와 theme-neutral, CLI를 설치하고 npm 스크립트를 달아, 코딩 에이전트와 사람이 `astryx component --list` 같은 같은 명령으로 컴포넌트 문서를 보게 해요.",
  "category": "개발",
  "categoryId": "dev",
  "topics": [
    {
      "id": "dev",
      "label": "개발"
    },
    {
      "id": "product",
      "label": "기획·디자인"
    },
    {
      "id": "personal",
      "label": "개인 생산성"
    }
  ],
  "difficulty": "입문",
  "tools": [
    "Astryx",
    "npm",
    "React"
  ],
  "whenToUse": "React 19 프로젝트에서 코딩 에이전트와 함께 UI를 만들 때, 둘이 같은 컴포넌트 문서를 보고 일관되게 작업하게 하고 싶을 때 써요.",
  "prerequisites": [
    "React 19 이상 프로젝트 (react, react-dom)",
    "Node와 npm, pnpm, yarn 중 하나"
  ],
  "inputs": [
    {
      "name": "project_dir",
      "label": "프로젝트 폴더",
      "description": "Astryx를 설치할 React 프로젝트 경로",
      "example": "~/projects/my-app",
      "required": true
    }
  ],
  "howToFollow": "1. 입력값(inputs)을 사용자에게 받아 프롬프트의 {{이름}} 자리에 넣을 것. 필수값이 없으면 먼저 물어볼 것.\n2. 단계를 순서대로 진행할 것. kind가 \"ai\"면 프롬프트를 실행하고, \"command\"면 사용자의 허락을 받고 명령을 실행하고, \"human\"이면 사용자에게 할 일을 안내하고 끝났는지 물을 것. tool이 있으면 그 도구·모델로 할 것.\n3. 단계에 output(결과 이름)이 있으면 그 단계 결과를 뒤 단계 프롬프트의 {{output}} 자리에 넣을 것.\n4. 단계마다 expected(기대 결과)와 check(확인 방법)로 제대로 됐는지 확인하고, 다르면 다음 단계로 넘어가지 말고 사용자에게 알릴 것. 끝나면 example.output(있으면)과 비교할 것.\n5. 검증 상태가 verified가 아니면 그 사실을 사용자에게 먼저 알릴 것. 답에 url을 출처로 밝힐 것.",
  "steps": [
    {
      "n": 1,
      "kind": "command",
      "title": "패키지 설치",
      "body": "프로젝트 폴더에서 core, 테마, StyleX 피어 의존성을 설치하고 CLI는 개발 의존성으로 설치해요. pnpm이나 yarn을 쓰면 `pnpm add`, `yarn add`로 바꿔요.",
      "prompt": "npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex\nnpm install -D @astryxdesign/cli",
      "expected": "package.json에 @astryxdesign/core, @astryxdesign/theme-neutral, @stylexjs/stylex와 개발 의존성 @astryxdesign/cli가 들어가요.",
      "check": "package.json의 dependencies와 devDependencies를 열어 확인해요.",
      "tool": "npm"
    },
    {
      "n": 2,
      "kind": "command",
      "title": "CLI를 전역에도 설치 (선택)",
      "body": "컴퓨터에 한 번 설치하면 어느 폴더에서나 `astryx`가 되고 코딩 에이전트도 Astryx를 알게 돼요. 프로젝트 안에서는 그 프로젝트의 버전이 실행돼요. 프로젝트 설치와 전역 설치를 모두 하는 것을 권장해요.",
      "prompt": "npm i -g @astryxdesign/cli",
      "expected": "전역에서 astryx 명령이 잡혀요.",
      "check": "`astryx docs global`로 전역 모드 설명이 나오는지 봐요.",
      "tool": "npm"
    },
    {
      "n": 3,
      "kind": "human",
      "title": "CSS 가져오기와 테마 프로바이더 설정",
      "body": "빌드 플러그인이나 PostCSS, Babel 설정 없이 CSS 몇 줄과 테마 프로바이더만 넣으면 돼요. Next.js, Tailwind, Vite, CDN별 방법은 @astryxdesign/core README의 Quick Start를 따라요.",
      "expected": "앱이 Astryx 테마가 적용된 상태로 떠요.",
      "check": "개발 서버를 켜고 Astryx 컴포넌트 하나를 렌더링해 스타일이 적용되는지 봐요.",
      "tool": "packages/core README"
    },
    {
      "n": 4,
      "kind": "command",
      "title": "package.json에 astryx 스크립트 추가",
      "body": "AI 도우미나 새 팀원이 CLI를 직접 부를 때 경로 오류가 나지 않게 스크립트를 달아요.",
      "prompt": "\"scripts\": {\n  \"astryx\": \"node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs\"\n}",
      "expected": "scripts에 astryx 항목이 생겨요.",
      "check": "`npm run astryx -- component --list`가 컴포넌트 목록을 출력하는지 확인해요.",
      "tool": "npm"
    },
    {
      "n": 5,
      "kind": "human",
      "title": "에이전트와 사람이 같은 CLI로 문서 보기",
      "body": "에이전트에게 UI를 맡길 때 `npm run astryx -- component --list`로 컴포넌트를 찾고 그 문서를 기준으로 만들라고 안내해요. 사람도 같은 명령으로 같은 문서를 봐요. 전역 설치와 프로젝트 설치 비교는 `astryx docs global/project-global-or-both`에서 볼 수 있어요.",
      "expected": "에이전트와 사람이 같은 CLI 문서를 기준으로 컴포넌트를 고르고 써요.",
      "check": "에이전트가 만든 UI가 목록에 있는 Astryx 컴포넌트로 짜였는지 코드로 확인해요.",
      "tool": "Astryx CLI"
    }
  ],
  "pitfalls": [
    "Astryx는 베타예요. API가 바뀔 수 있어요.",
    "@astryxdesign/charts와 @astryxdesign/vega는 @canary 태그로만 배포돼서 안정 버전이 없어요.",
    "@astryxdesign/lab은 npm에 배포되지 않아요.",
    "CLI 경로를 직접 부르면 에이전트가 경로 오류를 낼 수 있어요. npm 스크립트로 부르세요."
  ],
  "sources": [
    {
      "title": "Astryx",
      "url": "https://github.com/meta/astryx/blob/590d90164198f68d7eea1eddee4cb93e90b69372/README.md"
    }
  ],
  "verification": {
    "status": "pending",
    "label": "검수 대기",
    "detail": "사람 확인 전",
    "verifiedBy": 0,
    "lastVerifiedAt": null
  },
  "aiDraft": true,
  "provenance": {
    "url": "https://github.com/meta/astryx/blob/590d90164198f68d7eea1eddee4cb93e90b69372/README.md",
    "repo": "meta/astryx",
    "path": "README.md",
    "commit": "590d90164198f68d7eea1eddee4cb93e90b69372",
    "license": "MIT",
    "author": "meta",
    "sourceDate": "2026-11-07T05:16:19+00:00"
  },
  "quality": {
    "score": 29,
    "components": {
      "result": 0.5,
      "trust": 0,
      "freshness": 0.3
    },
    "explanation": "확인 없음 · 검수 대기"
  },
  "workedFor": 0,
  "trials": {
    "summary": "",
    "lastAt": null,
    "total": 0,
    "worked": 0,
    "partial": 0,
    "failed": 0,
    "recent": []
  },
  "asOf": {
    "date": "2026-11-07T05:16:19+00:00",
    "basis": "source"
  },
  "updatedAt": "2026-11-08T16:43:33.179479+00:00"
}