Skip to content

AGENTS.md

Latest commit

 

History

History
77 lines (54 loc) · 5.83 KB

AGENTS.md

File metadata and controls

77 lines (54 loc) · 5.83 KB
Raw

SEED Design

디자인 토큰(Rootage)·Recipe(qvism)·CSS·React·Lynx 구현과 문서·Figma·MCP·CLI 도구를 함께 관리하는 Bun 모노레포다.

시작

  1. 학습 기록 관리 규칙을 읽고, 작업 경로·키워드로 메타데이터를 조회한 뒤 관련 활성 교훈만 읽어 계획에 반영한다.
  2. 루트부터 대상 경로까지의 AGENTS.md를 모두 읽는다. 하위 문서가 더 좁은 규칙과 검증 명령을 둔다.
  3. 여러 패키지에 걸친 변경이거나 어디서 시작할지 모르면 ARCHITECTURE.md를 읽는다.
  4. 테스트·TypeScript 코드를 쓰거나 의존성·changeset·릴리스를 다루면 TECH.md를 읽는다.
  5. 요청과 직접 관련된 코드·설정·문서만 연다.

검증

변경 경로의 명령만 실행한다. 하위 AGENTS.md에 검증 명령이 있으면 그것을 따른다. 문서·AGENTS.md·Skill처럼 실행 동작이 없는 변경은 내용·링크·형식 검토로 끝낸다.

  • packages/react-headless/*/ → bun headless:test
  • packages/react/ → bun react:test
  • packages/lynx-react/, packages/lynx-react-headless/*/ → bun test:lynx-react
  • packages/rootage/, ecosystem/rootage/ → bun rootage:test
  • docs/ → bun docs:test
  • tools/extract-api-surface/ → bun --filter @seed-design/extract-api-surface test && bun --filter @seed-design/extract-api-surface typecheck
  • .github/scripts/build-api-surface-diff-comment.ts, .github/scripts/list-public-packages.ts → bun test ./.github/scripts/build-api-surface-diff-comment.test.ts ./.github/scripts/list-public-packages.test.ts
  • 그 밖에 테스트가 있는 경로 → bun test <경로>. 예: bun test packages/cli, bun test ecosystem/qvism
  • 여러 패키지에 걸친 변경을 마칠 때 → bun test:all

함정:

  • React 테스트는 headless 패키지의 lib/ 빌드를 import한다. headless를 고쳤거나 lib/가 없으면 CI처럼 bun utils:build && bun headless:build를 먼저 실행한다. Lynx는 bun lynx-headless:build다.
  • 루트 bun test는 **/lynx-react*/**를 제외한다. Lynx 패키지는 bun test:lynx-react(typecheck + Vitest)로 돌린다.
  • bun rootage:test의 validator는 미사용 schema property를 지우며 원본 YAML을 다시 쓸 수 있다. 실행 뒤 git diff로 의도한 변경만 남았는지 확인한다.

생성

생성물은 직접 고치지 않는다. git check-attr linguist-generated -- <파일>이 set이면 생성물이다. 원천은 .gitattributes이고, 수동 관리 예외는 해당 패키지 AGENTS.md에 있다.

  1. 원천을 고친다.
  2. 영향받는 단계만 실행한다.
    • packages/rootage/ YAML → bun rootage:generate && bun qvism:generate
    • packages/qvism-preset/src/recipes/, packages/lynx-qvism-preset/src/recipes/ → bun qvism:generate
    • docs/registry/ → bun docs:generate
    • 범위가 넓거나 불확실함 → bun generate:all
  3. git diff로 의도한 생성물만 바뀌었는지 확인한다.

생성 명령이 성공했는데 생성물이 그대로면 bun ecosystem:build && bun install 후 다시 실행한다. workspace bin 링크가 없으면 다른 CLI가 조용히 실행된다. 원천과 산출물의 대응은 ARCHITECTURE.md「생성 파이프라인」에 있다.

경계

사용자에게 먼저 확인할 작업:

  • 새 패키지나 외부 의존성 추가
  • tsconfig, biome.json, .github/workflows/ 변경
  • 데이터 삭제, Git 복원·브랜치 전환, 외부 서비스 쓰기, publish, merge
  • 요청받지 않은 commit, push, PR 생성·갱신. 단, 학습 기록 관리 규칙에 따른 학습 항목 커밋은 확인 없이 한다.

그 밖의 읽기·로컬 수정·테스트·생성은 묻지 않고 진행한다. 확인이 필요한 작업도 준비와 로컬 검증은 먼저 끝낸다.

  • 패키지 매니저는 bun만 쓴다. 의존성은 bun add로 바꾸고 bun.lock은 손으로 고치지 않는다.
  • 포맷은 변경한 파일만 bun biome format --write <파일>로 맞춘다.
  • .env, API key, secret은 읽거나 커밋하지 않는다.
  • 사용자 요청이 Skill 지침보다 우선한다. Skill 지침 때문에 멈추거나 방향을 바꾸면 근거가 된 SKILL.md 경로와 문장을 사용자에게 밝힌다.
  • Lynx 기기에서 open·reload·화면 조작을 하기 전에 session 소유권과 Card 수명을 읽고 따른다. 여러 에이전트·worktree가 같은 client를 공유한다.

학습 기록

학습 기록은 .agents/learnings/에서 관리한다. 에이전트가 작성·관리하고 사람이 검토할 수 있는 저장소 내부 기록이며, 읽기·기록·정리·커밋 절차는 해당 경로의 AGENTS.md를 따른다.

문서

  • AGENTS.md: 에이전트 규칙·명령·경계. .agents/learnings/: 에이전트가 쌓는 교훈. ARCHITECTURE.md: 패키지 경계·생성 파이프라인·변경 유형별 시작 경로. TECH.md: 저장소 공통 기술 규칙. README.md·CONTRIBUTING.md: 사람용.
  • 새 규칙은 가장 좁은 적용 경로의 AGENTS.md에 두고 상위 문서에 반복하지 않는다.
  • 하위 AGENTS.md는 # <경로> 제목과 1–2문장 개요로 시작하고, 내용이 있는 섹션만 둔다. 검증 명령이 있으면 ## 검증을 맨 앞에 두고, 그 밖에는 ## 규칙·## 작업 절차를 쓴다. 코드·설정으로 알 수 있는 내용과 일반론은 쓰지 않는다.
  • 에이전트 문서는 표 대신 짧은 목록, 한다체로 쓴다. 금지 규칙에는 대신 할 행동을 함께 쓴다.

Git

커밋 메시지와 PR 제목은 영어 Conventional Commits(type(scope): subject)로 쓴다. 예: feat(button): add loading state.