Files
persona-lenz/AGENTS.md
T

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, 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).

커맨드

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.