Communitygithub.com

reyalka/astro

Astro 모노레포 개발을 위한 종합 가이드입니다. 아키텍처, 디버깅, 테스트 및 중요한 제약 사항을 다룹니다. 기능 개발, 버그 수정, 테스트 작성 또는 코드베이스 구조 이해 시 사용하세요.

astro란 무엇인가요?

이 스킬은 AI 에이전트와 개발자가 Astro 모노레포에서 효과적으로 작업할 수 있도록 설계된 컨텍스트 로딩 스킬입니다. 작업 유형(코어 기능 추가, 버그 수정, 테스트, 통합 등)에 따라 적절한 문서를 추천하는 빠른 의사 결정 매트릭스를 제공합니다. `runtime/` 코드에서 Node.js API 사용 금지, 각 통합 테스트에 고유한 `outDir` 설정 필요, 그리고 세 가지 실행 컨텍스트(core, runtime/server, runtime/client) 간의 경계와 같은 중요한 제약 사항을 강조합니다. 또한 주요 파일 경로, 명령어 레퍼런스, 테스트 철학(단위 테스트 선호)을 포함하여 개발자가 모노레포의 구조와 규칙을 빠르게 파악하고 작업을 시작할 수 있도록 돕습니다. 버그 분류, GitHub Actions 로그 분석, 간단한 질문에는 사용하지 않는 것이 좋습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/reyalka/astro/tree/HEAD/.agents/skills/astro-developer
원본 보기→모든 스킬 둘러보기

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

문서

Astro 개발자 스킬

Astro 모노레포에서 작업하는 AI 에이전트와 개발자를 위한 컨텍스트 로딩 스킬입니다. 작업에 따라 관련 문서를 로드합니다.

빠른 의사 결정 매트릭스

무엇을 하고 계신가요? → 다음 파일을 읽으세요:

작업기본 문서보조 문서
코어 기능 추가architecture.md, constraints.mdtesting.md
버그 수정debugging.mdarchitecture.md
테스트 작성/수정testing.mdconstraints.md
통합 생성packages/integrations/ 에서 예제 확인testing.md
아키텍처 이해architecture.md-
오류 처리debugging.md, constraints.mdtesting.md
제약 사항 이해constraints.mdarchitecture.md

중요한 경고

시작하기 전에, 다음과 같은 일반적인 함정을 인지하세요:

  1. 단위 테스트 선호: 기본적으로 단위 테스트 가능한 코드를 작성하세요. 통합 테스트는 필요한 경우에만 사용하세요 → testing.md
  2. Node.js API 제한: runtime/ 코드에서는 Node.js API를 사용할 수 없습니다 → constraints.md
  3. 테스트 격리: 각 통합 테스트에 대해 고유한 outDir을 설정해야 합니다 → testing.md
  4. 런타임 경계: 코어 vs Vite vs 브라우저 실행 컨텍스트 → architecture.md
  5. 프리릴리스 모드: Changesets는 origin/next 브랜치를 대상으로 합니다 (.changeset/config.json 확인)

빠른 명령어 레퍼런스

# 개발
pnpm install                                    # 설치 (루트만)
pnpm run build                                  # 모든 패키지 빌드
pnpm run dev                                    # 감시 모드
pnpm run lint                                   # 린트 수행

# 테스트
pnpm -C packages/astro exec astro-scripts test "test/**/*.test.js"  # 모든 테스트
pnpm -C packages/astro exec astro-scripts test -m "pattern"         # 테스트 필터링
pnpm run test:e2e                               # E2E 테스트
node --test test/file.test.js                   # 단일 테스트

# 예제
pnpm --filter @example/minimal run dev          # 예제 실행

# 체인지셋
pnpm exec changeset --empty                     # 체인지셋 생성 (대화형 모드 없음)

주요 파일 경로

packages/astro/src/
├── core/              # Node.js 실행 컨텍스트 (빌드/개발 명령어)
├── runtime/
│   ├── server/        # Vite SSR 실행 컨텍스트
│   └── client/        # 브라우저 실행 컨텍스트
├── virtual-modules/   # 가상 모듈 진입점
├── content/           # 콘텐츠 레이어 시스템
├── vite-plugin-*/     # Vite 플러그인
└── types/             # 중앙 집중식 TypeScript 타입

packages/integrations/  # 공식 통합
예제/              # 변경 사항 테스트
test/fixtures/         # 테스트 픽스처

참고: node_modules/의 오류 스택 추적은 packages/의 소스로 매핑됩니다. 자세한 내용은 architecture.md를 참조하세요.

사용법

이 스킬은 관련 컨텍스트를 로드할 뿐, 워크플로를 조정하지는 않습니다. 적절한 문서를 로드한 후:

  1. 작업에 권장되는 파일을 읽으세요
  2. 설명된 패턴과 제약 사항을 적용하세요
  3. 제공된 명령어와 파일 경로를 사용하세요
  4. 문제가 발생하면 문서에서 오류 메시지를 검색하세요

아키텍처 빠른 요약

세 가지 실행 컨텍스트:

  • core/ → Node.js, 빌드/개발 명령어, Vite 플러그인 외에는 Node API 사용 금지
  • runtime/server/ → Vite SSR, Node API 사용 불가
  • runtime/client/ → 브라우저, Node API를 전혀 사용할 수 없음

다섯 가지 파이프라인 유형:

  • RunnablePipeline → Vite 로더 시스템이 있는 astro dev
  • NonRunnablePipeline → 런타임 모듈 로딩이 없는 astro dev (Cloudflare 어댑터)
  • BuildPipeline → astro build + 사전 렌더링
  • AppPipeline → 프로덕션 서버리스/SSR
  • ContainerPipeline → 컨테이너 API

전체 세부 사항은 architecture.md를 참조하세요.

테스트 빠른 요약

철학: 통합 테스트보다 단위 테스트를 선호합니다. 기본적으로 단위 테스트 가능한 코드를 작성하세요.

단위 테스트 (빠름, 선호):

  • 순수 함수와 비즈니스 로직 테스트
  • 인프라에서 비즈니스 로직 추출
  • 의존성 주입 사용

통합 테스트 (느림, 드물게 사용):

  • 단위 테스트할 수 없는 기능에만 사용 (가상 모듈, 전체 빌드 파이프라인)
  • 캐시 오염을 방지하기 위해 항상 고유한 outDir 설정

전체 패턴과 예제는 testing.md를 참조하세요.

이 스킬을 사용하지 말아야 할 경우

  • 버그 분류: 대신 triage 스킬을 사용하세요
  • GitHub Actions 분석: 대신 analyze-github-action-logs 스킬을 사용하세요
  • 간단한 질문: 그냥 직접 질문하고, 이 스킬을 로드하지 마세요

관련 문서

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

reyalka/astro

Analyze recent GitHub Actions workflow runs to identify patterns, mistakes, and improvements. Use when asked to "analyze workflow logs", "review action runs", or "analyze GitHub Actions".

reyalka/astro

Independently implement and validate an alternative solution for an Astro pull request. Use only for Factory's adversary blue team.

reyalka/astro

Qualify and compare red and blue solutions for an Astro pull request using Astro-specific merge and tie-break criteria. Use only for Factory's adversary purple team.

reyalka/astro

Perform a static, read-only code review of an Astro pull request or of a local branch, commit range, diff, patch, or working tree being prepared as a pull request. Determine whether the change satisfies its stated business requirements and is good enough to merge, using the PR description, linked requirement issues and roadmap items, and PR or issue discussions when available. Use this skill only for PR review or self-review, not issue triage or bug investigation. It reports only merge-relevant findings and never edits code or runs project code, tests, builds, checks, or scripts.

reyalka/astro

Write and update Astro pull requests with reviewer-friendly titles and high-signal bodies. Trigger whenever the user asks to create a PR, open a PR, draft a PR, update PR title/body, or write PR notes/summary/description.

reyalka/astro

Handle main-to-next merge tasks including conflict resolution, changeset cleanup, and CI fix-ups. Use when merging main into next.

reyalka/astro

How to write JSDoc (/** */) and inline (//) comments in the Astro codebase, for contributors reading the source — not end users. Use whenever writing or editing comments in .ts/.js source, including comments added incidentally while fixing bugs or building features. Does not cover the @docs-generated config/error reference.

관련 스킬

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community