kikita-labs/kikita-create-nestjs-app

kikita-create-nestjs-app은(는) 무엇을 하나요?

NestJS 프로젝트를 부트스트래핑하고 해당 AGENTS.md / .agents/ 문서 트리를 생성하여, 이후 해당 프로젝트에서 작업하는 모든 AI 에이전트(Claude Code, Codex 등)가 완벽하고 스스로 유지 관리 가능한 단일 진실 공급원을 가지도록 합니다.

0. 모드 감지 (항상 먼저 수행)

대상 디렉토리에서 .agents/.kikita-scaffold.json 파일을 확인합니다.

• 없음 → 새로 초기화. 아래 1번 섹션으로 진행한 후 plan.md를 따릅니다.
• 있음 → 이 프로젝트는 이미 이 스킬로 스캐폴딩되었습니다. update.md를 대신 따르십시오. 질문지를 다시 실행하거나 재스캐폴딩하지 마십시오. update.md는 최신 템플릿을 가져오고, 기록된 커밋 이후의 변경 사항을 비교(diff)한 후, 프로젝트의 (사용자 정의되었을 수 있는) .agents/ 파일에 변경 사항을 병합하는 작업을 처리합니다.

0.5. 사전 조건 (새 초기화 시에만)

• 작업 디렉토리가 비어 있거나 사용자가 명시적으로 여기서 초기화하기를 원하는지 확인합니다.
• 먼저 묻지 않고 관련 없는 프로젝트가 이미 있는 디렉토리에서 이 스킬을 실행하지 마십시오.

1. 질문지 (파일 시스템에 접근하기 전에 항상 질문)

여기서부터 plan.md를 단계별로 따르십시오. 질문지를 건너뛰지 마십시오. 완료되면 사용자에게 완료되었다고 알리기 전에 checklist.md를 실행하십시오.

12개의 질문을 한 번에 던지는 것이 아니라 두 단계로 질문하십시오. 첫 번째 답변에 따라 이후 질문의 관련성이 결정되므로, 모든 질문을 미리 제시하는 것은 봇 전용 사용자에게 해당되지 않는 "REST API 인증" 질문을 하게 됩니다.

1단계 — 분기 질문 (단독):

1. 애플리케이션 유형: REST API, 봇, 또는 동일한 앱에서 둘 다?
   • 봇(또는 둘 다)인 경우: 어떤 플랫폼? Telegram (nestjs-telegraf) 또는 Discord — 그리고 Discord의 경우 necord가 권장되는 기본값입니다(네이티브 Nest DI/가드/파이프를 통한 일반적인 이벤트→핸들러→서비스 패턴을 만족시키는 글루 코드가 가장 적음). 그러나 필수 사항은 아닙니다. 사용자가 원시 discord.js를 원하는 경우(기존 팀 전문성, necord가 아직 래핑하지 않은 discord.js 기능) 이는 합법적인 선택입니다. 아래 "다른 플랫폼"과 동일하게 취급하여 일반적인 패턴을 수동으로 적용하십시오(무료로 제공받는 대신).
   • 다른 플랫폼/라이브러리(이름을 지정하십시오 — architecture/transport-adapter.md의 일반 봇 전송 패턴은 이에 맞게 조정되지만, 구체적인 어댑터 코드는 nestjs-telegraf/necord 외의 항목에 대해 수동으로 작성해야 합니다).

2단계 — 나머지 모든 질문 (배치, 질문 3은 1단계에서 REST 또는 "둘 다"라고 답한 경우에만 질문, 아래의 다른 모든 질문은 애플리케이션 유형에 관계없이 적용):

2. 테스트: 없음, 또는 단위 / e2e (Supertest) / 둘 다? "둘 다"는 실제 Postgres 인스턴스를 대상으로 하는 통합 테스트를 위해 Testcontainers도 연결합니다.
3. 인증 (1단계에서 봇 전용이면 완전히 건너뜁니다): 필요합니까? "예"는 하나의 고정된 검증된 패턴을 스캐폴딩합니다(메뉴가 아님). core/auth.md의 스캐폴드 블록을 참조하십시오: 수명이 짧은 액세스 토큰(5-15분, 쿠키에 절대 저장되지 않음) + /auth/refresh로 범위가 지정된 httpOnly 쿠키의 리프레시 토큰 + 순환(일회용, DB에 해시됨) + 리프레시 엔드포인트의 csrf-csrf + argon2id 비밀번호 해싱 + RolesGuard. 대안(세션, 순환 없는 베어 JWT)을 제공하지 마십시오. 이것이 유일한 기본값입니다.
4. 백그라운드 작업: BullMQ (Redis 기반 큐)를 사용합니까?
5. 캐싱: @nestjs/cache-manager + @keyv/redis (캐시-어사이드)를 사용합니까? 기본 권장 사항은 아니오입니다. 모든 CRUD 엔드포인트에 추측성으로 추가하지 말고 실제 성능 필요가 있을 때 추가하십시오.
6. 파일 업로드: 필요합니까? 그렇다면 추가 하위 질문은 없습니다. 스토리지 벤더(개발 시 로컬 디스크, 프로덕션 시 모든 S3 호환 버킷: AWS S3, MinIO, R2, Spaces)는 환경 변수이지 스캐폴드 타임 선택 사항이 아닙니다.
7. 비동기 메시징 / 서비스 간 이벤트: 필요합니까? 그렇다면 브로커에 대한 추가 하위 질문도 없습니다. RabbitMQ가 고정된 기본값입니다(작업 큐, 라우팅, DLQ가 대부분의 경우를 처리함). architecture/messaging.md는 이벤트 스트리밍/재생/극한 처리량 요구 사항을 위한 후속 마이그레이션 경로로 Kafka를 문서화하며, 스캐폴드 타임 옵션이 아닙니다.
8. i18n: 이 프로젝트에 여러 로케일이 필요합니까? 번역된 REST 오류/유효성 검사 메시지 및/또는 둘 이상의 언어로 된 봇 응답? 그렇다면 추가 하위 질문은 없습니다. nestjs-i18n이 고정된 라이브러리입니다. 로케일 확인은 전송 방식에 따라 다릅니다(REST: Accept-Language 헤더, 봇: 플랫폼 자체의 사용자별 로케일 필드, 절대 Accept-Language 아님). 둘 다 core/i18n.md에서 다룹니다. 아니오인 경우 건너뜁니다. 한 가지 언어로만 실행될 프로젝트에는 필요하지 않습니다.
9. 공개 API의 JSDoc/TSDoc: 모든 내보낸 심볼에 필수 문서 주석을 적용합니까, 아니면 건너뜁니까? .agents/agent-surface.md 생성 여부를 결정합니다(권장 기본값: 예).
10. Git 정책: 에이전트가 매번 묻지 않고 커밋하고 푸시할 수 있습니까, 아니면 모든 커밋/푸시가 확인되어야 합니까?
11. 패키지 매니저: npm, pnpm 또는 yarn? 기본 권장 사항: pnpm.
12. Git 리모트: 사용자가 이미 푸시할 리포지토리 URL을 가지고 있습니까? 그렇다면 기록하십시오. git remote add origin <url>은 git init 직후에 실행됩니다(plan.md 참조). URL이 주어지지 않으면 건너뜁니다. 사용자가 나중에 직접 리모트를 연결합니다.

모든 답변을 기록하십시오. 답변은 스캐폴딩과 생성할 문서 파일을 모두 결정합니다. 위에 명시적으로 고정된 것 외에는 절대 기본값을 조용히 가정하지 마십시오. 사용자가 질문을 건너뛰면 해당 질문에 대해 다시 물어보십시오. 이 스킬은 단일 NestJS 프로젝트를 대상으로 하며, 모노레포/Nx 워크스페이스나 분산 마이크로서비스 토폴로지(여러 배포 가능한 서비스/리포지토리)를 대상으로 하지 않습니다. 사용자가 둘 중 하나를 원하면 이 스킬이 그것을 다루지 않는다고 말하고 즉흥적으로 진행하지 말고 중단하십시오. 메시지 브로커(질문 7 참조)는 단일 앱 내에서 하이브리드 앱(app.connectMicroservice())만 연결하며, 두 번째 서비스를 생성하지 않습니다.

고정된 기본값 — 절대 이에 대해 묻지 마십시오. 설계상 고정되어 있습니다:

• ORM/DB: Prisma + Postgres. TypeORM 없음(새 프로젝트에 권장되지 않음), Drizzle 없음(틈새 성능/에지 선택), 이 스킬의 v1에서 NoSQL/MongoDB 분기 없음.
• 유효성 검사: HTTP 계층의 class-validator + class-transformer, main.ts에 무조건 whitelist, forbidNonWhitelisted, forbidUnknownValues, transform이 모두 true로 설정된 전역 ValidationPipe. env/config 유효성 검사(Zod 사용: @nestjs/config + validate), 스키마 파일 외부에서 직접 process.env를 읽는 것을 차단하는 ESLint 규칙으로 적용됨 — testing-and-quality.md의 "Mechanically Enforced Rules" 참조. 중첩된 DTO 필드에는 @ValidateNested()와 @Type(() => NestedDto)가 모두 필요합니다. code-style/dto-and-validation.md 참조. @nestjs/swagger에서 가져온 PartialType/OmitType/PickType을 통한 DTO 재사용, 절대 @nestjs/mapped-types 사용 금지 — 문서화뿐만 아니라 ESLint에 의해 차단됨(같은 섹션).
• 응답 형태: 전역 ClassSerializerInterceptor + DTO 필드의 @Exclude()가 하나의 고정된 직렬화 메커니즘입니다. 원시 Prisma 엔터티가 반환되지 않으며, ADR 없이 두 번째 직렬화 접근 방식이 도입되지 않습니다.
• Swagger/OpenAPI: REST 브랜치에 대해 항상 연결됩니다.
• CORS: 환경 변수 기반 origin 허용 목록을 통해 main.ts에서 항상 구성되며, 절대 *를 사용하지 않습니다.
• API 버전 관리: Nest URI 버전 관리(/v1/...), architecture/transport-adapter.md에 고정됨.
• 속도 제한: @nestjs/throttler가 REST 및/또는 봇에 대해 항상 설치되며, REST 경로의 경우 IP 기반, 봇 핸들러의 경우 사용자/채팅-ID 기반 — "아직 필요하지 않음"으로 건너뛰지 않음.
• 로깅: nestjs-pino, 항상 사용. 구조화된 JSON 로그, 일반 Logger 옵션 제공 안 함.
• 헬스 체크: @nestjs/terminus, 항상 연결되며 질문지에 포함되지 않음 — 두 개의 별도 라우트, GET /health/live (프로세스 전용, 외부 검사 없음) 및 GET /health/ready (Prisma + 선택한 Redis/RabbitMQ 종속성), 절대 하나로 병합되지 않음. core/health.md 참조.
• 정상 종료: main.ts에서 항상 app.enableShutdownHooks() 호출 — 이 호출이 없으면 컨테이너 재시작 시 Prisma의 OnModuleDestroy 연결 종료 훅이 실행되지 않습니다.
• Prisma 오류 매핑: 전역 PrismaExceptionFilter (APP_FILTER)가 PrismaClientKnownRequestError 코드를 해당하는 Nest HTTP 예외로 매핑합니다. Prisma 오류가 처리되지 않은 500 오류로 표면화되지 않습니다.
• Prisma 클라이언트 생성: package.json에 항상 "postinstall": "prisma generate"가 추가됩니다. 생성된 클라이언트는 gitignore에 포함되므로, 새 클론/CI에서 컴파일하려면 이것이 필요합니다.
• docker-compose.yml: 항상 생성됨(개발/테스트 전용, 프로덕션 배포에서 절대 참조되지 않음). Postgres는 항상 포함, BullMQ 및/또는 캐싱이 선택된 경우에만 Redis 추가(둘 다에 대해 하나의 공유 인스턴스), 메시징이 선택된 경우에만 RabbitMQ 추가.

2. 생성

plan.md를 따르십시오. templates/에서 대상 프로젝트로 파일을 복사합니다. 점 파일(.gitignore, .gitattributes, .editorconfig, .prettierrc, .prettierignore, .nvmrc, .vscode/extensions.json, .env.example, docker-compose.yml)을 포함합니다.

질문지 답변으로 두 가지 다른 작업이 수행됩니다. 혼동하지 마십시오.

• 텍스트 플레이스홀더 — 모든 {{TOKEN}}을 실제 값으로 찾아서 바꾸고, 남겨두지 마십시오: {{PROJECT_NAME}}, {{APP_TYPE}}, {{BOT_PLATFORM}}, {{TESTS}}, {{GIT_POLICY}}, {{PACKAGE_MANAGER}}, {{NODE_VERSION}}, {{DATE}}.
• 포함 게이트(Inclusion gates) — 애플리케이션 유형, 봇 플랫폼, 테스트, 인증, 큐, 캐시, 스토리지, 메시징, i18n 및 필수 TSDoc 답변은 플레이스홀더를 채우지 않습니다. 전체 파일(또는 파일 내의 <!-- SCAFFOLD -->로 표시된 블록)이 전혀 복사될지 여부를 결정합니다. "아니오" 답변은 파일/블록이 빈 문자열로 채워지는 것이 아니라 삭제됨을 의미합니다. 게이트된 파일은 유지될 때 여전히 AGENTS.md / 관련 README에서 링크되어야 하며, 건너뛸 때 해당 링크가 제거되어야 합니다.

3. 확인

성공을 보고하기 전에 checklist.md를 완전히 실행하십시오.

문서 구조에 대한 참고 사항 (한 번 읽고 템플릿/을 그대로 따르십시오)

• CLAUDE.md는 항상 AGENTS.md를 가리키는 한 줄짜리 스텁입니다.
• AGENTS.md는 필수 진입점입니다: 프로젝트 루트에 짧은 "Must Read" 목록과 절대 협상 불가 규칙이 있습니다.
• .agents/README.md는 .agents/ 아래의 모든 항목에 대한 플랫 인덱스입니다. 조건부 파일(auth, queue, cache, storage, messaging, i18n, agent-surface)이 추가되거나 건너뛸 때 동기화 상태를 유지하십시오.
• 진정으로 하나의 짧은 문서로 충분한 주제는 .agents/*.md (workflow, git-policy, documentation, testing-and-quality, agent-surface, refactoring, progress)에 평평하게 유지됩니다.
• 여러 문서로 확장되거나 기능별 레지스트리가 있는 주제는 자체 README.md 허브와 함께 하위 폴더를 얻습니다: .agents/code-style/, .agents/architecture/, .agents/shared/, .agents/core/, .agents/decisions/.
• .agents/shared/README.md는 src/common/을 등록합니다(프레임워크에 구애받지 않는 유틸리티 — @nestjs/* 가져오기가 없으며, 일반적인 파이프/필터/인터셉터/데코레이터 추가). .agents/core/README.md는 src/core/ 앱 전체 싱글톤(인증, Prisma 클라이언트 제공자, 로거, 큐, 캐시, 스토리지, i18n — 각 기능이 선택된 경우 해당 조건부 문서 파일과 함께)을 등록합니다.
• .agents/decisions/README.md는 짧은 ADR이 필요한 시점(계층 방향, 메시지 브로커 마이그레이션, 버전 관리 전략 변경)을 설명합니다. 항상 생성되며, ADR 파일 없이 시작됩니다.
• 추적된 모든 파일 내용(TSDoc 포함)은 영어만 사용합니다. 키릴 문자나 모지바케가 없습니다.
• .agents/의 모든 문서는 kikita-create-angular-app의 템플릿처럼 읽혀야 합니다: 명령형, 짧음, 예제 기반, 검토/확인 체크리스트로 끝남.