원문: https://github.com/facebook/astryx/wiki/Contributing-with-AI-Assistants · 번역 기준: 2026-09-03

AI 어시스턴트(Claude, Codex 등)의 도움을 받아 Astryx OSS에 기여하기 위한 가이드입니다.

핵심 아이디어

Astryx는 빠르게 움직이지만, 단계를 건너뛰어서가 아닙니다. 모든 컴포넌트 변경은 — "작은" prop 추가조차 — 올바른 문제를 올바른 방식으로 해결하고 있음을 보장하는 specification protocol을 거칩니다. AI 어시스턴트는 강력한 구현 파트너지만, 사용 패턴과 디자인 의도를 이해하는 사전 작업을 대체할 수는 없습니다.

이 가이드는 그 프로토콜, 여러분의 탐구가 가장 가치 있는 지점, 그리고 기여를 성공적으로 안착시키는 방법을 설명합니다.

안전한 탐구 영역 (Safe Exploration Zones)

이 영역들은 디자인 주도 기여에 적합하며 전체 spec protocol이 필요하지 않습니다:

Storybook Stories (apps/storybook/stories/)

story는 사람들이 시스템을 배우는 방법입니다. 디자인 기여자는 이를 개선하기에 특별히 유리한 위치에 있습니다:

• 현실적인 composition — 고립된 prop만이 아니라 맥락 속의 컴포넌트를 보여주세요. badge, status dot, avatar 셀이 있는 Table story는 <Table data={data} />보다 더 많은 것을 가르칩니다.
• 패턴 시연 — 흔한 UI 패턴(설정 페이지, 대시보드, list-detail 뷰)을 위해 컴포넌트들이 어떻게 함께 조합되는지 보여주세요.
• 엣지 케이스 — 긴 텍스트, empty state, loading state, 밀도 높은 레이아웃. API가 실제로 동작하는지 드러내는 케이스들입니다.
• Theme 커버리지 — 컴포넌트가 여러 theme과 모드에서 올바르게 보이는지 검증하세요.

story는 기존 컴포넌트 API를 사용합니다. 패키지 변경 불필요, spec protocol 불필요.

Sandbox 페이지 (apps/sandbox/src/app/(sandbox)/pages/)

sandbox는 현실적인 페이지 레이아웃에서 컴포넌트를 테스트하기 위한 Next.js 앱입니다. 다음을 하기에 가장 좋은 곳입니다:

• 페이지 template 프로토타이핑 — 여러 컴포넌트를 함께 사용하는 전체 페이지 레이아웃을 만들어보세요.
• composition 테스트 — story가 다루지 않는 방식으로 컴포넌트를 조합해보세요.
• gap 드러내기 — 기존 컴포넌트로 필요한 것을 만들 수 없다면, 그것은 가치 있는 신호입니다. gap을 설명하는 이슈를 제출하세요(새 prop을 추가하는 PR이 아니라).