Files

96 lines
5.3 KiB
Markdown

# 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`, then `planning-and-task-breakdown`.
- Implementation: use `incremental-implementation` and `test-driven-development`.
- Bug or failing behavior: use `debugging-and-error-recovery` and `test-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).
## 커맨드
```sh
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_VERSION` bump.
- 이미 저장된 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.