shinpr/ai-coding-project-boilerplate

다른 언어로 읽기: 日本語

Claude Code를 위한 에이전트 기반 코딩 스타터 키트(Agentic coding starter kit) 및 워크플로우 보일러플레이트(boilerplate) — 서브 에이전트(sub-agents), 컨텍스트 엔지니어링(context engineering), 그리고 컨텍스트 고갈(context exhaustion) 없는 환경을 통해 프로덕션 수준의 TypeScript 프로젝트를 구축하세요.

⚡ 이 보일러플레이트는 다음과 같은 개발자를 위한 것입니다:

• AI 기반 워크플로우로 TypeScript 프로젝트를 더 빠르게 구축하고자 하는 개발자

• 긴 AI 코딩 세션 중 **컨텍스트 고갈 (context exhaustion)**을 피하고 싶은 개발자

• **특화된 AI 에이전트 (specialized AI agents)**를 통해 팀 워크플로우를 표준화하고자 하는 개발자

• 빠른 시작 (3단계)

• 기존 프로젝트 업데이트하기

• 바이브 코딩 (Vibe Coding)을 넘어: 왜 서브 에이전트인가?

• 슬래시 명령어 (Slash Commands)

• 스킬 (Skills) 커스터마이징

• 스킬 시스템 (Skills System)

• 이 보일러플레이트로 구축된 프로젝트

• 문서 및 가이드

• 개발 워크플로우

• 프로젝트 구조

• 패키지 매니저 설정

• 다국어 지원

• FAQ

# 1. 프로젝트 생성
npx create-ai-project my-project
# 2. 의존성 설치 (자동)
...

💡

처음이신가요? 상세한 설정 안내를 위해 빠른 시작 가이드를 확인하세요.

프로젝트의 에이전트 정의, 명령어, 스킬 및 AI 규칙을 최신 상태로 유지하세요. 프로젝트의 루트 디렉토리에서 실행하십시오:

# 적용하지 않고 변경 사항 미리보기
npx create-ai-project update --dry-run
# 업데이트 적용
...

npx create-ai-project update를 실행하면 CLI는 다음을 수행합니다:

• 현재 버전에 대한 프로젝트의 .create-ai-project.json 매니페스트(manifest)를 확인합니다.
• 최신 패키지 버전과 비교합니다.
• 검토를 위한 변경 로그(CHANGELOG)를 보여줍니다.
• 관리되는 파일들을 최신 버전으로 교체합니다.
• 설정된 언어 설정에 따라 활성 디렉토리를 재생성합니다.

대상	경로
에이전트 정의 (Agent definitions)	.claude/agents-{lang}/
...

사용자의 소스 코드 (src/), package.json, 그리고 기타 프로젝트 파일은 절대 건드리지 않습니다.

파일을 커스터마이징하여 덮어쓰기를 원하지 않는 경우:

# 무시 목록에 추가
npx create-ai-project update --ignore skills project-context
npx create-ai-project update --ignore agents task-executor
...

무시된 파일들은 업데이트 중에 보존됩니다. 파일을 무시할 경우 다른 업데이트된 구성 요소들과 버전 불일치(version mismatch)가 발생할 수 있음에 유의하십시오.

만약 업데이트 기능이 도입되기 전에 프로젝트를 생성했다면, 프로젝트의 루트 디렉토리(root directory)에서 npx create-ai-project update를 실행하기만 하면 됩니다. 그러면 .claudelang 파일로부터 언어를 감지하여 매니페스트(manifest)를 자동으로 초기화합니다.

팀들이 바이브 코딩(vibe coding)을 넘어, 구조화된 워크플로우를 전문화된 AI 에이전트(AI agents)에게 위임하는 **에이전틱 코딩 (agentic coding)**이 실질적인 접근 방식으로 주목받고 있습니다. 이 보일러플레이트(boilerplate)는 Claude Code 서브 에이전트(sub-agents)를 사용하여 해당 접근 방식을 구현합니다.

전통적인 AI 코딩의 어려움:

• ❌ 긴 세션 동안 컨텍스트(context)를 상실함
• ❌ 시간이 지남에 따라 코드 품질이 저하됨
• ❌ 대규모 작업을 위해 빈번하게 세션을 재시작해야 함

서브 에이전트는 컨텍스트 엔지니어링 (context engineering)을 통해 이를 해결합니다:

• ✅ 작업을 전문화된 역할(설계, 구현, 리뷰)로 분할
• ✅ 각 에이전트가 새롭고 집중된 컨텍스트를 할당받음 — 소진(exhaustion) 없음
• ✅ 품질 저하 없이 대규모 프로젝트 처리

이는 Claude Code의 서브 에이전트 메커니즘이 각 에이전트를 자체적인 컨텍스트 윈도우(context window)에서 실행하기 때문에 가능합니다. 부모 세션이 작업을 위임하면, 각 서브 에이전트는 깨끗하고 집중된 컨텍스트로 시작합니다. 품질 검사(lint, 타입 체크, 테스트, 빌드)는 CI가 아닌 각 커밋(commit) 전에 로컬에서 실행됩니다. 피드백 루프는 빠르게 유지되며, 코드는 푸시(push)될 때 이미 검증된 상태가 됩니다.

TypeScript 프로젝트에서 함께 작동하는 서브 에이전트들

Claude Code를 위한 필수 명령어:

명령어	목적	사용 시점
/implement	엔드 투 엔드 (End-to-end) 기능 개발	새로운 기능 추가 시
/task	기술 기반의 정밀도를 가진 단일 작업	버그 수정, 작은 변경 사항
/design	설계 문서만 생성	아키텍처 계획 시
/plan	설계로부터 작업 계획 생성	설계 승인 후
/prepare-implementation	/build를 위한 계획 준비 (준비 상태 확인 및 공백 해결)	계획이 구현 가능한지 확인하기 위해 /build 실행 전
/build	기존 계획으로부터 실행	작업 재개 시
/review	코드 준수 여부 확인	구현 완료 후
/diagnose	문제 진단 워크플로우	디버깅, 트러블슈팅
/reverse-engineer	코드로부터 PRD/설계 문서 생성	레거시 시스템 문서화
/create-skill	대화형 대화를 통해 새로운 스킬 생성	프로젝트 특화 규칙 추가 시
/refine-skill	품질 검토를 통한 기존 스킬 수정	스킬 정확도 향상 시

프론트엔드 대응 명령어 (/front-design (UI 사양 + 설계 문서용), /front-build, /front-review, /front-plan) 및 유틸리티 명령어 (/add-integration-tests, /update-doc)도 사용할 수 있습니다.

이 보일러플레이트(Boilerplate)에는 즉시 사용할 수 있는 범용 스킬들이 포함되어 있습니다. 하지만 스킬은 여러분의 코딩 컨벤션(Coding conventions), 도메인 제약 조건(Domain constraints), 그리고 팀의 결정 사항에 맞춰 프로젝트에 맞게 조정할 때 그 잠재력을 최대한 발휘합니다.

포함된 스킬들을 기준점(Baseline)으로 생각하세요. 다음 단계는 그것들을 여러분의 것으로 만드는 것입니다:

— 프로젝트 특화 전제 조건 캡처 (한 번 실행하며, 매 세션마다 참조됨) /project-inject
— 대화형 대화를 통해 새로운 스킬 생성 /create-skill
— 최적화 검토를 통해 기존 스킬 개선 /refine-skill

효과적인 스킬 작성을 위한 원칙과 모범 사례는 Skills Editing Guide를 참조하세요.

스킬을 만드는 것과, 그 스킬이 실제로 에이전트의 행동을 개선하는지 아는 것은 별개의 문제입니다. 스킬은 서로 상호작용하며 프로젝트 컨텍스트 (Project Context)와도 상호작용하므로, 이를 확인하는 유일하게 신뢰할 수 있는 방법은 스킬이 있을 때와 없을 때를 실행하여 결과를 비교하는 것입니다.

rashomon은 이를 위한 Claude Code 플러그인입니다. 스킬 변경이 상황을 개선했다는 것에 대해 직관이 아닌 증거를 원할 때 이를 사용하세요.

이 보일러플레이트 (Boilerplate)는 에이전트적 구현 워크플로우 (Agentic Implementation Workflows)에서 사용되는 원칙들을 스킬로 제공하며, 필요에 따라 일상적인 작업에서 참조할 수 있도록 합니다.

스킬	목적
coding-standards	보편적인 코딩 원칙, 안티 패턴 (Anti-patterns), 디버깅
typescript-rules	TypeScript 타입 안정성 (Type Safety), 비동기 패턴 (Async Patterns), 리팩토링 (Refactoring)
typescript-testing	Vitest, TDD, 커버리지 요구사항
documentation-criteria	PRD, ADR, 디자인 문서 (Design Doc), UI 사양 (UI Spec) 표준
technical-spec	아키텍처 (Architecture), 환경 (Environment), 빌드 명령 (Build Commands)
implementation-approach	전략 패턴 (Strategy Patterns), 작업 분해 (Task Decomposition)
integration-e2e-testing	통합 테스트 및 투-레인 E2E (Two-lane E2E; fixture-e2e / service-integration-e2e), ROI 기반 선택, 저니 정의 (Journey Definition)
frontend-typescript-rules	React 컴포넌트 설계, Props 중심 패턴 (Props-driven patterns)
frontend-typescript-testing	React Testing Library, MSW, Playwright E2E (fixture 및 service-integration 패턴)
frontend-technical-spec	React 아키텍처, 환경, 데이터 흐름 (Data Flow)
project-context	AI 정확도를 위한 프로젝트별 전제 조건 (/project-inject를 통해 설정)

이 보일러플레이트가 없을 경우: 설정 및 인프라 구축에 약 1주일 소요
이 보일러플레이트가 있을 경우: 프로덕션 준비 완료 단계까지 약 2일 소요

Sub Agents MCP Server — Claude Code/Cursor CLI를 서브 에이전트 (Sub Agents)로 사용할 수 있게 하는 MCP 서버
⏱️ 초기 개발 2일 — 테스트 코드가 코드베이스의 약 90%를 차지하며, 현재 프로덕션 환경에서 사용 중

MCP Image Generator — Gemini API를 통한 AI 이미지 생성
⏱️ 초기 개발 1.5일 — 다중 이미지 블렌딩 (Multi-image blending) 및 캐릭터 일관성 (Character consistency)을 갖춘 완전한 크리에이티브 도구

두 가지 모두 기본 /implement 워크플로우 (workflow)를 사용하여 구축되었으며, 수동적인 에이전트 오케스트레이션 (agent orchestration)이 필요하지 않습니다.

다음 프로젝트들을 확인해 보세요: sub-agents-mcp ・ mcp-image

빠른 시작 가이드 (Quick Start Guide)

• 5분 안에 실행하기

사용 사례 및 명령어 (Use Cases & Commands)

• 일상적인 워크플로우 참조

스킬 편집 가이드 (Skills Editing Guide)

• AI를 위한 라이브러리 문서, 팀 규칙 및 프로젝트별 지식 추가

디자인 철학 (Design Philosophy)

• 이 접근 방식이 효과적인 이유

graph LR
A[Requirements] --> B[Scale Detection]
B -->|Small| C[Direct Implementation]
...

기존 코드로부터 PRD 및 디자인 문서 (Design Docs) 생성:

graph TB
subgraph Phase1[Phase 1: PRD Generation]
SD[scope-discoverer] --> PRD[prd-creator]
...

요구사항 분석 (Requirement Analysis): /implement 명령어가 작업 규모를 분석합니다.
문서 생성 (Document Generation): 필요한 문서(PRD, UI Spec, 디자인 문서, 작업 계획)를 생성합니다.
작업 실행 (Task Execution): 전문화된 에이전트 (agents)가 각 단계를 처리합니다.
품질 보증 (Quality Assurance): 자동 테스트, 타입 체크 (type checking) 및 수정 작업을 수행합니다.
커밋 및 계속 (Commit & Continue): 완료된 각 작업에 대해 깔끔한 커밋을 수행합니다.

ai-coding-project-boilerplate/
├── .claude/ # AI 에이전트 (agent) 설정
│ ├── agents/ # 전문화된 서브 에이전트 (sub-agent) 정의
...

이 보일러플레이트 (boilerplate)는 기본적으로 npm을 사용하지만, bun 또는 pnpm과 같이 선호하는 패키지 매니저 (package manager)로 전환할 수 있습니다.

package.json에는 환경에 따라 달라지는 두 가지 설정이 있습니다:

packageManager: 사용할 패키지 매니저 및 버전
scripts: 각 스크립트에 대한 실행 명령어

이 설정을 변경하면 Claude Code가 이를 인식하고 적절한 명령어로 실행합니다.

{
"packageManager": "bun@1.3.3",
"scripts": {
...

위의 내용은 대표적인 예시입니다. 다음 스크립트들은 스킬 (skills) 및 서브 에이전트 (sub-agent) 정의에서 참조됩니다. 필요에 따라 업데이트하십시오:

build, dev, type-check, test, test:coverage, test:coverage:fresh, test:safe, cleanup:processes, check, check:fix, check:code, check:unused, check:deps, check:all, format, format:check, lint, lint:fix

영어 및 일본어 완전 지원:

npm run lang:en # 영어로 전환
npm run lang:ja # 일본어로 전환
npm run lang:status # 현재 언어 확인

모든 설정(configurations), 규칙(rules), 그리고 에이전트 정의(agent definitions)를 자동으로 업데이트합니다.

Q: 서브 에이전트(sub agents)는 어떻게 작동하나요?

A: 그냥 /implement 또는 /task를 사용하세요. 적절한 에이전트들이 자동으로 활성화됩니다.

Q: 에러가 발생하면 어떻게 하나요?

A: quality-fixer가 대부분의 문제를 자동으로 수정합니다. 그렇지 않은 경우, 명확한 지침을 제공합니다.

Q: 제 프로젝트에 맞춰 커스텀할 수 있나요?
A: 네! /project-inject를 실행하여 프로젝트별 필수 요구 사항(prerequisites)을 설정하세요. 이 정보는 실행 정확도를 높이기 위해 매 세션 시작 시 AI가 읽어 들입니다.

Q: AI가 제 라이브러리 문서(llms.txt, API 레퍼런스 등)를 참조하게 할 수 있나요?
A: 네 — .claude/skills/ 아래에 관련 URL을 포함한 커스텀 스킬(custom skill)을 생성하세요. 자세한 내용은 스킬 편집 가이드(Skills Editing Guide)를 참조하세요.

Q: 일반적인 워크플로우(workflow)는 어떻게 되나요?
A: /project-inject (1회 실행) → /implement (기능 구현) → 자동 품질 검사 (auto quality checks) → 커밋 (commit)

Q: Copilot/Cursor와는 무엇이 다른가요?
A: 해당 도구들은 코드 작성 보조에 집중합니다. 이 보일러플레이트(boilerplate)는 전문화된 에이전트들에 의해 관리되는 구조화된 개발 라이프사이클(development lifecycle)을 제공합니다.

Q: 에이전틱 코딩(agentic coding)이란 무엇이며, 이 보일러플레이트는 이를 어떻게 지원하나요?
A: 에이전틱 코딩은 대화형 프롬프팅(conversational prompting)에 의존하는 대신, 구조화된 워크플로우를 전문화된 AI 에이전트들에게 위임하는 방식입니다. 이 보일러플레이트는 사전 구성된 서브 에이전트(sub-agents), CLAUDE.md 규칙, 그리고 품질 검사 기능을 제공하므로, 직접 스캐폴딩(scaffolding)을 구축할 필요 없이 해당 접근 방식을 채택할 수 있습니다.

Q: 컨텍스트 고갈(context exhaustion)을 어떻게 방지하나요?
A: 컨텍스트 엔지니어링(context engineering)을 통해 방지합니다. 각 서브 에이전트는 단일 책임에 집중하는 자체 컨텍스트 윈도우(context window)에서 실행되므로, 세션 길이에 상관없이 컨텍스트가 신선하게 유지됩니다. 저희는 품질 저하 없이 77만 개 이상의 토큰(770K+ token) 세션을 실행했습니다 — 자세한 내용은 설계 철학(design philosophy) 포스트를 참조하세요.

요구사항 분석(requirement analysis), UI 사양(UI specification), 설계(design), 계획(planning), 구현(implementation), 품질 보증(quality assurance), 코드 리뷰(code review), 디버깅(debugging), 그리고 역공학(reverse engineering)을 포함하여 전체 개발 생명주기(development lifecycle)를 아우르는 20개 이상의 특화된 서브 에이전트(sub-agents)가 포함되어 있습니다. 각 에이전트는 집중된 실행을 위해 각자의 컨텍스트 윈도우(context window) 내에서 실행됩니다.

MIT License - 자유롭게 사용, 수정 및 배포 가능

AI Coding Project Boilerplate는 특화된 서브 에이전트(sub-agents)와 컨텍스트 엔지니어링(context engineering)을 사용하여, 요구사항 분석부터 자동화된 품질 검사까지 Claude Code에 구조화된 개발 생명주기(development lifecycle)를 제공합니다. 각 에이전트는 각자의 컨텍스트 윈도우(context window)에서 집중된 작업을 처리하며, 이를 통해 긴 세션 동안 일관된 품질을 유지합니다. 이 보일러플레이트(boilerplate)에는 사전 구성된 CLAUDE.md 규칙, 커스텀 스킬(custom skills), 슬래시 명령어(slash commands)가 포함되어 있어, 직접 도구를 조립할 필요 없이 에이전트 기반 워크플로우(agentic workflows)를 사용하여 TypeScript 프로젝트 구축을 바로 시작할 수 있습니다.

Claude Code와 함께 즐거운 코딩 되세요! 🤖✨