designpaca 초기 구현 — 스킬 · 설치 CLI · 배포 파이프라인

웹 디자인 파이프라인 스킬과 이를 5개 에이전트에 설치하는 CLI 를 담은 모노레포.

스킬 (packages/skill)
- SKILL.md 261줄 + 참조 문서 16개 3,349줄. progressive disclosure 로
  본문은 절차와 인덱스만, 지식은 references/ 로 분리
- 0~6단계 파이프라인. 규모에 따라 전체·연장·국소 세 경로로 분기
- 하드 게이트 12개는 grep·카운트로 검증 가능한 것만. 취향 판단은 제외
- 미학 프리셋 5종, AI 슬롭 지문 목록, 한글 조판 규칙,
  SVG 필터·three.js·인터랙티브 모션·HTML-in-Canvas 실전 지침

설치 CLI (packages/cli, packages/core)
- npx designpaca 온보딩 TUI. Claude Code · Codex · Cursor · Windsurf · AGENTS.md
- 매니페스트에 설치 시점 해시를 기록해 사용자가 고친 파일은 update 가 건너뛴다
- 타깃별로 본문의 references/ 경로를 실제 설치 위치로 재작성
- AGENTS.md 는 항상 로드되므로 본문 대신 303자 포인터만 주입
- Windsurf 는 12,000자 상한 초과 시 설치를 차단

배포 (build/ci, .forgejo/workflows)
- 태그 v* → 검사·테스트·빌드 → npmjs 배포 + Forgejo 레지스트리 미러
  → draft 릴리스 → Cloudflare Pages. 재실행 멱등

근거 (research/)
- 약 250개 웹 소스 조사 결과와 도그푸딩 검증 2건. 스킬의 모든 수치는 여기서 나온다

테스트 22개 통과 (core 16 · cli 6)

packages/core/src/targets/agents-md.ts

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { exists } from "../fsx.ts";
+import type { FileAction, TargetAdapter, TargetContext } from "../types.ts";
+import { MARKER, rewriteRefPaths, skillDirActions } from "./common.ts";
+
+/**
+ * 범용 AGENTS.md — 어떤 에이전트든 읽는 프로젝트 루트 문서에 우리 블록만 심는다.
+ * 문서 전체를 덮어쓰지 않는다. 블록 밖은 사용자 것이다.
+ *
+ * **본문 전체를 넣지 않는다.** AGENTS.md 는 스킬과 달리 조건 없이 항상 로드되고,
+ * Codex 는 병합 결과를 기본 32KiB 에서 자른다. 14KB 짜리 본문을 넣으면
+ * 디자인과 무관한 모든 대화에서 그 비용을 내고, 프로젝트 자신의 지침이 잘려나갈 수 있다.
+ * 그래서 여기에는 포인터만 두고 본문은 .designpaca/ 에 풀어둔다.
+ */
+export const agentsMd: TargetAdapter = {
+  id: "agents-md",
+  label: "범용 AGENTS.md",
+  hint: "AGENTS.md 에 포인터 주입 — 에이전트 무관",
+  scopes: ["project", "user"],
+
+  async detect(ctx: TargetContext) {
+    // 항상 로드되는 자리라 기본 선택은 보수적으로 — AGENTS.md 가 실제로 있을 때만.
+    return (
+      (await exists(path.join(ctx.cwd, "AGENTS.md"))) ||
+      (await exists(path.join(ctx.home, ".codex", "AGENTS.md")))
+    );
+  },
+
+  async plan(ctx: TargetContext) {
+    const isUser = ctx.scope === "user";
+    const doc = isUser
+      ? path.join(ctx.home, ".codex", "AGENTS.md")
+      : path.join(ctx.cwd, "AGENTS.md");
+    // user/project 가 같은 구조를 갖도록 둘 다 .designpaca 를 루트로 쓴다
+    const refRoot = isUser
+      ? path.join(ctx.home, ".designpaca", "skill")
+      : path.join(ctx.cwd, ".designpaca");
+    const refPrefix = isUser ? "~/.designpaca/skill" : ".designpaca";
+
+    const block = [
+      "## designpaca — 웹 디자인 파이프라인",
+      "",
+      "이 리포에서 UI 를 새로 만들거나 다시 디자인할 때는, 마크업·스타일을 쓰기 전에",
+      `\`${refPrefix}/SKILL.md\` 를 읽고 그 파이프라인(0~6단계)을 따른다.`,
+      "",
+      "- 프로젝트 루트에 `design.md` 가 있으면 그것이 최상위다. 스킬 기본값을 덮는다.",
+      "- 참조 문서는 각 단계에서 지시하는 것만 그때 연다. 처음부터 전부 읽지 마라.",
+      "",
+      `<!-- designpaca v${ctx.skill.version} — \`npx designpaca update\` 가 관리한다. 직접 고치면 업데이트가 멈춘다. -->`,
+    ].join("\n");
+
+    // 본문은 별도 디렉터리에 통째로 푼다. 경로 재작성이 필요하다.
+    const skillActions = skillDirActions(refRoot, {
+      ...ctx.skill,
+      skillMd: rewriteRefPaths(ctx.skill.skillMd, refPrefix),
+    });
+
+    const actions: FileAction[] = [
+      { kind: "inject", path: doc, marker: MARKER, content: block },
+      ...skillActions,
+    ];
+
+    return {
+      target: this.id,
+      scope: ctx.scope,
+      root: refRoot,
+      actions,
+      alreadyInstalled: await exists(path.join(refRoot, "SKILL.md")),
+    };
+  },
+};

packages/core/src/targets/claude-code.ts

@@ -0,0 +1,34 @@
+import path from "node:path";
+import { exists } from "../fsx.ts";
+import type { TargetAdapter, TargetContext } from "../types.ts";
+import { anyExists, scopeRoot, skillDirActions } from "./common.ts";
+
+/**
+ * Claude Code — ~/.claude/skills/designpaca/ (전역) 또는 .claude/skills/designpaca/ (프로젝트).
+ * SKILL.md 포맷을 그대로 쓰므로 변환이 없다.
+ */
+export const claudeCode: TargetAdapter = {
+  id: "claude-code",
+  label: "Claude Code",
+  hint: "~/.claude/skills/designpaca — SKILL.md 그대로",
+  scopes: ["user", "project"],
+
+  async detect(ctx: TargetContext) {
+    return anyExists([
+      path.join(ctx.home, ".claude"),
+      path.join(ctx.cwd, ".claude"),
+      path.join(ctx.home, ".claude.json"),
+    ]);
+  },
+
+  async plan(ctx: TargetContext) {
+    const root = scopeRoot(ctx, [".claude", "skills", "designpaca"], [".claude", "skills", "designpaca"]);
+    return {
+      target: this.id,
+      scope: ctx.scope,
+      root,
+      actions: skillDirActions(root, ctx.skill),
+      alreadyInstalled: await exists(path.join(root, "SKILL.md")),
+    };
+  },
+};

packages/core/src/targets/codex.ts

@@ -0,0 +1,34 @@
+import path from "node:path";
+import { exists } from "../fsx.ts";
+import type { TargetAdapter, TargetContext } from "../types.ts";
+import { anyExists, scopeRoot, skillDirActions } from "./common.ts";
+
+/**
+ * Codex CLI — ~/.codex/skills/designpaca/.
+ * Codex 도 Claude Code 와 같은 SKILL.md 규약을 쓴다(실측: ~/.codex/skills/frontend-design 등).
+ */
+export const codex: TargetAdapter = {
+  id: "codex",
+  label: "Codex CLI",
+  hint: "~/.codex/skills/designpaca — SKILL.md 그대로",
+  scopes: ["user", "project"],
+
+  async detect(ctx: TargetContext) {
+    return anyExists([
+      path.join(ctx.home, ".codex"),
+      path.join(ctx.home, ".codex", "AGENTS.md"),
+      path.join(ctx.cwd, ".codex"),
+    ]);
+  },
+
+  async plan(ctx: TargetContext) {
+    const root = scopeRoot(ctx, [".codex", "skills", "designpaca"], [".codex", "skills", "designpaca"]);
+    return {
+      target: this.id,
+      scope: ctx.scope,
+      root,
+      actions: skillDirActions(root, ctx.skill),
+      alreadyInstalled: await exists(path.join(root, "SKILL.md")),
+    };
+  },
+};

packages/core/src/targets/common.ts

@@ -0,0 +1,60 @@
+import path from "node:path";
+import { exists } from "../fsx.ts";
+import type { FileAction, SkillSource, TargetContext } from "../types.ts";
+
+/** 매니페스트·마커에 쓰는 고정 식별자 */
+export const MARKER = "designpaca";
+
+/** 스킬 디렉터리를 통째로 쓰는 타깃(Claude Code·Codex)이 공유하는 파일 목록 */
+export function skillDirActions(root: string, skill: SkillSource): FileAction[] {
+  const actions: FileAction[] = [
+    { kind: "write", path: path.join(root, "SKILL.md"), content: skill.skillMd },
+  ];
+  for (const [rel, content] of skill.files) {
+    actions.push({ kind: "write", path: path.join(root, ...rel.split("/")), content });
+  }
+  // 업그레이드 판정에 쓰는 버전 스탬프
+  actions.push({
+    kind: "write",
+    path: path.join(root, ".designpaca_version"),
+    content: `${skill.version}\n`,
+  });
+  return actions;
+}
+
+/** references 를 별도 디렉터리로 내보내는 타깃(Cursor·AGENTS.md)용 */
+export function referenceActions(root: string, skill: SkillSource): FileAction[] {
+  const actions: FileAction[] = [];
+  for (const [rel, content] of skill.files) {
+    actions.push({ kind: "write", path: path.join(root, ...rel.split("/")), content });
+  }
+  actions.push({
+    kind: "write",
+    path: path.join(root, ".designpaca_version"),
+    content: `${skill.version}\n`,
+  });
+  return actions;
+}
+
+/**
+ * 본문의 `references/...` 상대 경로를 실제 설치 위치로 바꾼다.
+ *
+ * Claude Code·Codex 는 스킬 디렉터리를 통째로 복사하므로 상대 경로가 그대로 맞다.
+ * Cursor·Windsurf·AGENTS.md 는 본문만 다른 자리로 옮기고 references 는 별도 디렉터리에 풀기
+ * 때문에, 재작성하지 않으면 본문이 가리키는 경로가 전부 존재하지 않는 곳을 가리킨다.
+ */
+export function rewriteRefPaths(body: string, prefix: string): string {
+  return body.replaceAll("references/", `${prefix}/references/`);
+}
+
+/** 어느 한 경로라도 있으면 그 도구가 설치돼 있다고 본다 */
+export async function anyExists(paths: string[]): Promise<boolean> {
+  for (const p of paths) if (await exists(p)) return true;
+  return false;
+}
+
+export function scopeRoot(ctx: TargetContext, userRel: string[], projectRel: string[]): string {
+  return ctx.scope === "user"
+    ? path.join(ctx.home, ...userRel)
+    : path.join(ctx.cwd, ...projectRel);
+}

packages/core/src/targets/cursor.ts

@@ -0,0 +1,57 @@
+import path from "node:path";
+import { exists } from "../fsx.ts";
+import type { FileAction, TargetAdapter, TargetContext } from "../types.ts";
+import { anyExists, referenceActions, rewriteRefPaths } from "./common.ts";
+
+/** 본문과 references 가 함께 놓이는 루트 (본문 경로 재작성 기준) */
+const REF_PREFIX = ".cursor/rules/designpaca";
+
+/**
+ * Cursor — .cursor/rules/designpaca.mdc.
+ * .mdc 프론트매터는 SKILL.md 와 필드가 다르다(description/globs/alwaysApply)므로 변환한다.
+ *
+ * Windsurf 는 이 파일을 읽지 않는다(.windsurf/rules/*.md 를 쓴다) — 별도 어댑터로 분리했다.
+ */
+export const cursor: TargetAdapter = {
+  id: "cursor",
+  label: "Cursor",
+  hint: ".cursor/rules/designpaca.mdc — 프로젝트 단위",
+  // Cursor 의 전역 규칙은 파일이 아니라 앱 설정(User Rules)이라 프로젝트 범위만 지원한다
+  scopes: ["project"],
+
+  async detect(ctx: TargetContext) {
+    return anyExists([path.join(ctx.cwd, ".cursor"), path.join(ctx.home, ".cursor")]);
+  },
+
+  async plan(ctx: TargetContext) {
+    const rulesDir = path.join(ctx.cwd, ".cursor", "rules");
+    const mdc = path.join(rulesDir, "designpaca.mdc");
+    const refRoot = path.join(rulesDir, "designpaca");
+
+    const header = [
+      "---",
+      `description: ${ctx.skill.description}`,
+      "globs:",
+      "alwaysApply: false",
+      "---",
+      "",
+    ].join("\n");
+
+    const actions: FileAction[] = [
+      {
+        kind: "write",
+        path: mdc,
+        content: header + rewriteRefPaths(ctx.skill.body, REF_PREFIX),
+      },
+      ...referenceActions(refRoot, ctx.skill),
+    ];
+
+    return {
+      target: this.id,
+      scope: ctx.scope,
+      root: rulesDir,
+      actions,
+      alreadyInstalled: await exists(mdc),
+    };
+  },
+};

packages/core/src/targets/index.ts

@@ -0,0 +1,17 @@
+import type { TargetAdapter, TargetId } from "../types.ts";
+import { claudeCode } from "./claude-code.ts";
+import { codex } from "./codex.ts";
+import { cursor } from "./cursor.ts";
+import { windsurf } from "./windsurf.ts";
+import { agentsMd } from "./agents-md.ts";
+
+export const ADAPTERS: TargetAdapter[] = [claudeCode, codex, cursor, windsurf, agentsMd];
+
+export function getAdapter(id: TargetId): TargetAdapter {
+  const a = ADAPTERS.find((x) => x.id === id);
+  if (!a) throw new Error(`알 수 없는 설치 대상: ${id}`);
+  return a;
+}
+
+export { MARKER, rewriteRefPaths } from "./common.ts";
+export { claudeCode, codex, cursor, windsurf, agentsMd };

packages/core/src/targets/windsurf.ts

@@ -0,0 +1,66 @@
+import path from "node:path";
+import { exists } from "../fsx.ts";
+import type { FileAction, TargetAdapter, TargetContext } from "../types.ts";
+import { anyExists, referenceActions, rewriteRefPaths } from "./common.ts";
+
+const REF_PREFIX = ".windsurf/rules/designpaca";
+
+/** Windsurf 규칙 파일의 하드 상한. 넘으면 잘려서 조용히 망가진다. */
+const WINDSURF_CHAR_LIMIT = 12_000;
+
+/**
+ * Windsurf — .windsurf/rules/designpaca.md.
+ * Cursor 와 경로·프론트매터가 모두 다르다(trigger/globs, .mdc 아님).
+ *
+ * trigger 는 model_decision 을 쓴다. always_on 으로 두면 디자인 스킬이 모든 메시지의
+ * 시스템 프롬프트에 상주한다.
+ */
+export const windsurf: TargetAdapter = {
+  id: "windsurf",
+  label: "Windsurf",
+  hint: ".windsurf/rules/designpaca.md — 프로젝트 단위",
+  scopes: ["project"],
+
+  async detect(ctx: TargetContext) {
+    return anyExists([
+      path.join(ctx.cwd, ".windsurf"),
+      path.join(ctx.cwd, ".windsurfrules"),
+      path.join(ctx.home, ".windsurf"),
+    ]);
+  },
+
+  async plan(ctx: TargetContext) {
+    const rulesDir = path.join(ctx.cwd, ".windsurf", "rules");
+    const rule = path.join(rulesDir, "designpaca.md");
+    const refRoot = path.join(rulesDir, "designpaca");
+
+    const header = [
+      "---",
+      "trigger: model_decision",
+      `description: ${ctx.skill.description}`,
+      "---",
+      "",
+    ].join("\n");
+
+    const body = header + rewriteRefPaths(ctx.skill.body, REF_PREFIX);
+
+    const actions: FileAction[] = [
+      { kind: "write", path: rule, content: body },
+      ...referenceActions(refRoot, ctx.skill),
+    ];
+
+    return {
+      target: this.id,
+      scope: ctx.scope,
+      root: rulesDir,
+      actions,
+      alreadyInstalled: await exists(rule),
+      // 상한을 넘으면 설치는 되지만 Windsurf 가 뒷부분을 버린다. 조용히 깨지느니 막는다.
+      ...(body.length > WINDSURF_CHAR_LIMIT
+        ? {
+            blocked: `규칙 본문이 ${body.length}자로 Windsurf 상한(${WINDSURF_CHAR_LIMIT}자)을 넘는다. SKILL.md 를 줄여야 한다.`,
+          }
+        : {}),
+    };
+  },
+};