5.3 KiB
AGENTS.md
Use the local agent-skills workflows and Codex custom agents in this project.
Skill Usage
Before implementing, check whether a local skill in .agents/skills applies.
Intent mapping:
- Feature or significant change: use
spec-driven-development, thenplanning-and-task-breakdown. - Implementation: use
incremental-implementationandtest-driven-development. - Bug or failing behavior: use
debugging-and-error-recoveryandtest-driven-development. - Code review: use
code-review-and-quality. - Refactoring or simplification: use
code-simplification. - API/interface work: use
api-and-interface-design. - UI work: use
frontend-ui-engineering. - Security-sensitive work: use
security-and-hardening. - Performance work: use
performance-optimization.
Do not skip verification steps required by the selected skill.
Codex Custom Agents
Project-scoped custom agents are available in .codex/agents.
Use them explicitly when an isolated specialist pass is useful:
code-reviewer: review correctness, readability, architecture, security, performance, and tests.security-auditor: audit practical vulnerabilities and trust boundaries.test-engineer: analyze missing tests, test strategy, and verification quality.web-performance-auditor: audit Core Web Vitals and web performance risks.
For release readiness, spawn independent agents in parallel:
Spawn code-reviewer, security-auditor, and test-engineer in parallel on the current diff. Wait for all reports, then synthesize a go/no-go
decision.
Orchestration Rules
- The main Codex session is the orchestrator.
- Custom agents do not spawn other custom agents.
- Agents report findings back to the main session.
- The main session merges reports and decides next steps.
- Prefer skills for reusable workflows and custom agents for isolated specialist review.
Boundaries
- Always preserve existing project conventions.
- Always run the relevant tests or validation commands after changes.
- Ask before adding dependencies, changing CI, or making destructive changes.
- Never commit secrets or remove failing tests just to make checks pass.
persona-lenz
플레이스타일 벡터 기반 LoL 개인 분석 앱. Riot API 데이터로 유저 플레이스타일을 벡터화하고, 비슷한 스타일의 고티어 유저 비교·챔피언 추천·개선 피드백을 제공한다.
실행 플랜은 docs/PLAN.md를 따른다. 작업 순서, 스키마, API 스펙, 완료 기준이 모두 거기 정의되어 있다. 아이디어 원본(docs/archive/)과 충돌하면 PLAN.md가 우선이다.
구조
pnpm workspace 모노레포:
apps/api— NestJS 11 백엔드. HTTP API + BullMQ 프로세서 단일 프로세스apps/web— Vite + React 프론트엔드. dev proxy로/api→ api 서버packages/shared— API/web이 공유하는 DTO와 feature registry (@persona-lenz/shared)
DB는 MongoDB Atlas (mongoose), 큐/캐시는 Redis (BullMQ / node-redis).
커맨드
pnpm install
pnpm build # 전체 빌드 (--sort: shared 먼저)
pnpm start:api:dev # NODE_ENV=dev SECRET_SOURCE=infisical nest start --watch
pnpm start:web:dev
pnpm --filter api test # jest
규칙
- 시크릿은 코드/git에 절대 넣지 않는다. 모든 시크릿(RIOT_API_KEY, MONGODB_CONNECTION_STRING, REDIS_URL)은 Infisical에서
SecretService(apps/api/src/modules/global/secret/)를 통해 가져온다.process.env직접 참조 대신secretService.get(key). - Riot API 호출은 서버에서만 한다. 프론트에서 Riot API 직접 호출 금지.
- MongoDB 스키마는
apps/api/src/modules/global/database/schemas/에 컬렉션당 한 파일 (interface + SubSchema + Schema + index 선언 콜로케이션). 컬렉션명은 snake_case 단수 (riot_match). 모델은schemas/index.ts레지스트리에 등록하고ConnectionService.getModel()로 typed 접근. - DB 스키마 8종은 MVP 1~4를 견디도록 확정된 상태다 (docs/PLAN.md §4). 수정하지 말 것 — 변경이 필요하면 이유를 명시하고 사용자 확인을 받는다.
@persona-lenz/shared는 dist로 소비된다. shared 수정 후pnpm --filter @persona-lenz/shared build를 해야 api/web에 반영된다.- feature/vector 관련 metricId·차원·순서·baseline은
packages/shared/src/feature-registry.ts가 단일 진실 공급원. 지표 추가/변경 시FEATURE_SCHEMA_VERSIONbump. - 이미 저장된 Riot match는 재호출하지 않는다 (rate limit 보호).
- 작업 단위: 빌드 통과 + 테스트 통과 + 커밋. 커밋 메시지는 영어 명령형 한 줄.
- 작업 중 생성한 플랜/메모/요약 md 등 중간 산출물은 커밋하지 않는다. 커밋 대상 문서는 의도적으로 관리하는 문서(
AGENTS.md,docs/아래 문서)뿐이다. - 코드 주석은 한국어 가능. 식별자/타입명은 영어. 네이밍 규칙은 길어지더라도 맥락을 모두 담아낼 수 있는 이름으로 정한다. 예를 들어.
currentPlayer→currentBidRoundPlayer,timer→remainingBidRoundSeconds,maxTimer→maximumBidRoundDurationSeconds,deadline→currentBidRoundDeadlineTimestampMS
금지 사항 (Riot 정책)
MMR/ELO 계산기, 실시간 게임 중 정보 제공, API key 클라이언트 노출, Riot 공식 제휴로 보이는 표현. 상세는 docs/PLAN.md §1.3~1.4.