맥락과 모든 것
Claude의 답변 품질은 질문의 품질에 직접적으로 좌우됩니다. 문맥 당신이 제공하는. 맥락이 없는 완벽한 프롬프트는 일반적인 결과를 생성합니다. 간단한 프롬프트 풍부한 컨텍스트를 통해 프로젝트와 구체적이고 일관된 코드를 생성합니다.
이 기사에서는 리포지토리를 구성하는 방법, 지침 파일을 만드는 방법, Claude가 프로젝트를 깊이 이해할 수 있도록 시스템 프롬프트를 구성합니다.
무엇을 배울 것인가
- 이해를 극대화하기 위해 저장소 구조화
- CLAUDE.md 및 기타 컨텍스트 파일 생성
- 효과적인 시스템 프롬프트 구성
- 단일 저장소 및 다중 저장소 프로젝트 관리
- 긴 세션에서 맥락을 유지하기 위한 전략
시리즈 개요
"Claude: AI 기반 개인 프로젝트" 시리즈의 두 번째 글입니다.
| # | 기준 치수 | 상태 |
|---|---|---|
| 1 | 기초: 기술 파트너로서의 Claude | 완전한 |
| 2 | 프로젝트 컨텍스트 및 설정 | 당신은 여기에 있습니다 |
| 3 | 개념 및 요구사항 | 다음 |
| 4 | 백엔드 및 프런트엔드 아키텍처 | |
| 5 | 코드의 구조 | |
| 6 | 고급 엔지니어링 프롬프트 | |
| 7 | 테스트 및 품질 | |
| 8 | 선적 서류 비치 | |
| 9 | 배포 및 유지 관리 |
클로드가 컨텍스트를 처리하는 방법
Claude는 다음과 같은 컨텍스트 창을 가지고 있습니다. 토큰 200,000개 (약 150,000 단어) 이는 다른 LLM에 비해 크지만 전략적으로 관리해야 합니다.
창 컨텍스트: 작동 방식
| 요소 | 대략적인 토큰 | 메모 |
|---|---|---|
| 시스템 프롬프트 | 500 - 2,000 | 모든 요청에 항상 존재 |
| 클로드.md | 1,000 - 5,000 | 프로젝트 지침 |
| 코드 파일(중간) | 500 - 2,000 | 포함된 파일의 경우 |
| 대화 | 변하기 쉬운 | 시간이 지남에 따라 성장합니다. |
| 답변 | 최대 4,096명 | 기본 출력 제한 |
컨텍스트 우선순위
Claude는 정보의 위치에 따라 정보에 다른 가중치를 부여합니다.
컨텍스트 우선 순위 계층
1. SYSTEM PROMPT (massima priorità)
- Istruzioni su comportamento e stile
- Regole non negoziabili
- Sempre rispettate (se ben formulate)
2. CONTESTO RECENTE (alta priorità)
- Ultimi messaggi della conversazione
- File appena incollati
- Codice appena discusso
3. CONTESTO MEDIO (media priorità)
- Messaggi precedenti nella sessione
- File di documentazione inclusi
- Esempi forniti
4. CONTESTO LONTANO (bassa priorità)
- Inizio della conversazione
- Dettagli menzionati una volta
- Informazioni implicite
STRATEGIA: Ripeti le informazioni importanti
nei prompt successivi se la conversazione e lunga.저장소 구조
잘 구성된 저장소는 Claude가 프로젝트를 탐색하고 이해하는 데 도움이 됩니다. 모든 파일을 읽지 않고도 말이죠.
권장 구조
저장소 구조 - 모노 저장소
project-root/
├── CLAUDE.md # Istruzioni per Claude
├── README.md # Documentazione progetto
├── .cursorrules # (opzionale) Per Cursor IDE
├── docs/
│ ├── architecture.md # Decisioni architetturali
│ ├── api-spec.md # Specifiche API
│ └── adr/ # Architecture Decision Records
│ ├── 001-database-choice.md
│ └── 002-auth-strategy.md
│
├── apps/ # Mono-repo structure
│ ├── frontend/
│ │ ├── src/
│ │ ├── package.json
│ │ └── tsconfig.json
│ └── backend/
│ ├── src/
│ ├── package.json
│ └── tsconfig.json
│
├── packages/ # Shared code
│ └── shared-types/
│ └── src/
│
├── tools/
│ └── scripts/
│
├── .env.example # Variabili ambiente template
├── docker-compose.yml # Setup sviluppo locale
├── package.json # Root workspace
└── turbo.json # (se usi Turborepo)단일 저장소와 다중 저장소
모노레포
- 장점: 모든 것을 한 곳에서
- 장점: 원자적 리팩토링
- 장점: 단 하나의 CLAUDE.md
- 에 맞서: 많이 성장할 수 있어요
- 압형: 터보레포, Nx, 레르나
개인 프로젝트에 권장
다중 저장소
- 장점: 명확한 분리
- 장점: 독립적인 배포
- 에 맞서: 더 많은 오버헤드
- 에 맞서: 여러 CLAUDE.md
- 동조: Git 하위 모듈 또는 매뉴얼
팀이나 마이크로서비스에 더 적합
개인 프로젝트에 대한 조언
개인 프로젝트의 경우 모노 저장소. 모든 것을 한곳에 모아두세요 Claude에게 컨텍스트를 제공하고, 리팩터링하고, 일관성을 유지하는 것이 더 쉬워집니다. 다중 저장소의 복잡성은 단일 개발자의 이점을 정당화하지 않습니다.
CLAUDE.md 파일: 당신의 성경
파일 CLAUDE.md 클로드와 함께 일하는데 있어서 가장 중요한 문서입니다.
여기에는 Claude가 귀하를 효과적으로 돕기 위해 알아야 할 모든 것이 포함되어 있습니다.
완전한 템플릿 CLAUDE.md
CLAUDE.md - 완전한 템플릿
# CLAUDE.md - Project Instructions
## Quick Reference
- **Project:** TaskFlow - Time tracking and task management
- **Stack:** Angular 21 + Node.js 22 + PostgreSQL 16
- **Author:** Solo developer
- **Status:** MVP Development (Phase 1)
---
## Project Overview
### What It Does
TaskFlow helps freelancers track time spent on tasks and generate
client invoices. Core features include task CRUD, time tracking
with start/stop timers, and weekly reports.
### Target Users
Solo freelancers and small teams (1-5 people) who need simple
time tracking without enterprise complexity.
### Success Metrics
- User can create and track a task in under 30 seconds
- Weekly report generation in one click
- Mobile-responsive for on-the-go tracking
---
## Technical Architecture
### Frontend (apps/frontend)
```
Framework: Angular 21 (standalone components)
State: Signals + Services (no NgRx for MVP)
Styling: Tailwind CSS 4
Testing: Jest + Angular Testing Library
Build: Vite via Angular CLI
```
### Backend (apps/backend)
```
Runtime: Node.js 22 + Express 5
Language: TypeScript 5.5 (strict mode)
ORM: Prisma 6
Database: PostgreSQL 16
Auth: JWT + Refresh Tokens
Testing: Jest + Supertest
```
### Shared (packages/shared-types)
```
Purpose: TypeScript interfaces shared between FE/BE
Exports: DTOs, API types, enums, constants
```
---
## Coding Conventions
### TypeScript
- Strict mode enabled (no implicit any)
- Prefer `interface` over `type` for objects
- Use `readonly` for immutable properties
- Prefer `const` assertions for literals
### Naming
- **Variables:** camelCase (`userName`, `taskCount`)
- **Functions:** camelCase, verb prefix (`getUserById`, `calculateTotal`)
- **Classes:** PascalCase (`TaskService`, `UserController`)
- **Interfaces:** PascalCase, no `I` prefix (`User`, not `IUser`)
- **Files:** kebab-case (`user-profile.component.ts`)
- **Folders:** kebab-case (`time-entries/`)
- **Constants:** SCREAMING_SNAKE_CASE (`MAX_RETRY_COUNT`)
### Code Style
```typescript
// Prefer
const user = await userService.findById(id);
if (!user) throw new NotFoundError('User', id);
// Avoid
const user = await userService.findById(id);
if (user === null || user === undefined) {{ '{' }}
throw new Error('User not found');
{{ '}' }}
```
### Error Handling
- Use custom error classes (`ValidationError`, `NotFoundError`)
- Always include error codes for API responses
- Log with structured data (JSON), not string concatenation
- Never expose stack traces in production
---
## API Design
### URL Structure
```
GET /api/v1/tasks # List tasks
POST /api/v1/tasks # Create task
GET /api/v1/tasks/:id # Get single task
PATCH /api/v1/tasks/:id # Update task (partial)
DELETE /api/v1/tasks/:id # Soft delete task
```
### Response Format
```typescript
// Success
{{ '{' }} success: true, data: T {{ '}' }}
{{ '{' }} success: true, data: T[], meta: {{ '{' }} page, limit, total {{ '}' }} {{ '}' }}
// Error
{{ '{' }} success: false, error: {{ '{' }} code: string, message: string {{ '}' }} {{ '}' }}
```
### Status Codes
- 200: Success (GET, PATCH)
- 201: Created (POST)
- 204: No Content (DELETE)
- 400: Validation Error
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Error
---
## Current Development State
### Completed
- [x] Project scaffolding and mono-repo setup
- [x] Database schema design
- [x] User authentication (login/register)
- [x] JWT middleware
### In Progress
- [ ] Task CRUD endpoints
- [ ] Task list component
### Blocked
- (none currently)
### Next Up
- Time entries feature
- Dashboard with weekly summary
---
## Known Issues and Tech Debt
1. **Token Refresh:** Currently no automatic refresh on 401
2. **Validation:** Some DTOs missing validation decorators
3. **Tests:** Backend services at 60% coverage, need 80%
4. **Types:** Some `any` usages in legacy migration code
---
## DO NOT
These are strict rules - never violate them:
- Do NOT use `any` type (use `unknown` or proper generics)
- Do NOT skip error handling (always handle or propagate)
- Do NOT commit secrets (use environment variables)
- Do NOT use `console.log` in production code (use logger)
- Do NOT skip tests for new features
- Do NOT use synchronous file operations
- Do NOT use `var` (use `const` or `let`)
- Do NOT mix business logic in controllers
---
## Testing Requirements
### Unit Tests
- Every service method must have tests
- Mock external dependencies
- Aim for 80%+ coverage
### Integration Tests
- Every API endpoint must have tests
- Use test database (not mocks)
- Test success and error cases
### Naming Convention
```typescript
describe('TaskService', () => {{ '{' }}
describe('createTask', () => {{ '{' }}
it('should create a task with valid data', async () => {{ '{' }}
// ...
{{ '}' }});
it('should throw ValidationError when title is empty', async () => {{ '{' }}
// ...
{{ '}' }});
{{ '}' }});
{{ '}' }});
```
---
## Useful Commands
```bash
# Development
npm run dev # Start all apps in dev mode
npm run dev:frontend # Frontend only
npm run dev:backend # Backend only
# Building
npm run build # Build all apps
npm run typecheck # TypeScript check
# Testing
npm run test # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # With coverage report
# Database
npm run db:migrate # Run migrations
npm run db:seed # Seed development data
npm run db:studio # Open Prisma Studio
# Linting
npm run lint # Lint all
npm run lint:fix # Fix auto-fixable issues
```
---
## File Locations Quick Reference
| What | Where |
|------|-------|
| Frontend components | `apps/frontend/src/app/` |
| Backend controllers | `apps/backend/src/modules/*/controllers/` |
| Backend services | `apps/backend/src/modules/*/services/` |
| Database schema | `apps/backend/prisma/schema.prisma` |
| Shared types | `packages/shared-types/src/` |
| E2E tests | `apps/frontend/e2e/` |
| API tests | `apps/backend/src/modules/*/__tests__/` |
---
*Last updated: [DATE]*
*Maintained by: [YOUR NAME]*시스템 프롬프트: 지속적인 지침
프로젝트와 함께 Claude.ai를 사용할 때 다음을 정의할 수 있습니다. 시스템 프롬프트 모든 대화에 자동으로 포함됩니다. 클로드 코드의 경우, CLAUDE.md 파일도 비슷한 기능을 수행합니다.
Claude.ai 프로젝트에 대한 시스템 프롬프트
시스템 프롬프트 - 개발 템플릿
You are an expert software developer helping me build TaskFlow,
a time tracking and task management application.
## Your Role
- Technical partner and advisor
- Code reviewer with high standards
- Architecture consultant
## Technical Context
- Stack: Angular 21 + Node.js + PostgreSQL
- Style: TypeScript strict mode, functional where appropriate
- Architecture: Layered (Controller/Service/Repository)
## Response Guidelines
1. Always explain your reasoning before providing code
2. Point out potential issues or edge cases
3. Suggest tests for any new functionality
4. Be honest if you're uncertain about something
## Code Style
- TypeScript strict mode
- Prefer composition over inheritance
- Use descriptive names (avoid abbreviations)
- Include error handling in all examples
- Add JSDoc comments for public APIs
## When I Ask for Code
1. First, confirm you understand the requirement
2. Explain the approach you'll take
3. Provide the implementation
4. Suggest how to test it
5. Mention any caveats or limitations
## Communication
- Be concise but thorough
- Use bullet points for lists
- Use code blocks with proper language tags
- Ask clarifying questions when requirements are ambiguous지식 파일의 예
Claude.ai 프로젝트에서는 "지식 베이스"에 파일을 추가할 수 있습니다. 컨텍스트에 자동으로 포함됩니다.
기술 자료에 포함할 파일
| 파일 | 범위 | 우선 사항 |
|---|---|---|
CLAUDE.md |
전체 프로젝트 지침 | 필수적인 |
docs/architecture.md |
아키텍처 결정 | 높은 |
docs/api-spec.md |
API 사양 | 높은 |
tsconfig.json |
타입스크립트 구성 | 평균 |
package.json |
종속성 및 스크립트 | 평균 |
prisma/schema.prisma |
데이터베이스 스키마 | 높은 |
이름 지정 및 초기 구조
일관된 명명 규칙은 Claude가 일관된 코드를 생성하는 데 도움이 됩니다. 나머지 프로젝트와 함께.
일관된 명명 규칙
명명 규칙 - 전체 가이드
// ══════════════════════════════════════════════════════════════
// FILE NAMING
// ══════════════════════════════════════════════════════════════
// Components (Angular)
user-profile.component.ts // kebab-case + .component.ts
user-profile.component.html
user-profile.component.scss
// Services
user.service.ts // singular noun + .service.ts
task-api.service.ts // can have prefix
// Models/Interfaces
user.model.ts // singular + .model.ts
task.interface.ts // or .interface.ts
// DTOs
create-user.dto.ts // verb-noun + .dto.ts
update-task.dto.ts
// Tests
user.service.spec.ts // same name + .spec.ts
user.controller.test.ts // or .test.ts
// ══════════════════════════════════════════════════════════════
// CODE NAMING
// ══════════════════════════════════════════════════════════════
// Variables and Functions
const userName = 'John'; // camelCase
const taskList: Task[] = [];
function calculateTotalTime() {{ '{' }} {{ '}' }}
async function fetchUserById(id: string) {{ '{' }} {{ '}' }}
// Classes and Interfaces
class TaskService {{ '{' }} {{ '}' }} // PascalCase
interface UserProfile {{ '{' }} {{ '}' }}
type TaskStatus = 'TODO' | 'DONE';
// Constants
const MAX_RETRY_COUNT = 3; // SCREAMING_SNAKE_CASE
const API_BASE_URL = '/api/v1';
const DEFAULT_PAGE_SIZE = 20;
// Enums
enum TaskPriority {{ '{' }} // PascalCase enum name
Low = 'LOW', // PascalCase members
Medium = 'MEDIUM',
High = 'HIGH',
{{ '}' }}
// ══════════════════════════════════════════════════════════════
// FOLDER NAMING
// ══════════════════════════════════════════════════════════════
src/
├── components/ // plural, kebab-case
│ └── user-profile/ // kebab-case
├── services/
├── models/
├── utils/
└── shared/ // generic names OK초기 프로젝트 구조
프롬프트 - 초기 비계
Aiutami a creare la struttura iniziale per TaskFlow.
## REQUISITI
- Mono-repo con frontend Angular e backend Node.js
- Package shared per tipi TypeScript comuni
- Configurazione Turborepo per build/dev
- Setup Docker per sviluppo locale
## OUTPUT DESIDERATO
1. Albero directory completo
2. File package.json root con workspaces
3. tsconfig.json base
4. docker-compose.yml per PostgreSQL
5. Script npm per comandi comuni
## VINCOLI
- Niente framework di troppo (keep it simple)
- Preferisco Prisma per ORM
- Jest per tutti i test긴 세션을 위한 전략
긴 대화로 인해 Claude는 중요한 세부 사항을 "잊어버릴" 수 있습니다. 일관성을 유지하기 위한 전략은 다음과 같습니다.
1. 정기점검
프롬프트 - 컨텍스트 체크포인트
Prima di continuare, facciamo un checkpoint.
## RIEPILOGO SESSIONE
Abbiamo lavorato su:
1. Creazione del TaskService
2. Implementazione CRUD per i task
3. Testing del service
## DECISIONI PRESE
- Usiamo Signals per lo state management
- Soft delete per i task (deleted_at timestamp)
- Validazione lato service, non controller
## PROSSIMI STEP
- Implementare il controller
- Creare le route
Confermi che questo riassunto è corretto?2. 상태 파일
SESSION-STATE.md - 세션 추적
# Session State - 2025-01-31
## Current Focus
Implementing Task module backend
## Files Modified This Session
- apps/backend/src/modules/tasks/task.service.ts (created)
- apps/backend/src/modules/tasks/task.repository.ts (created)
- apps/backend/prisma/schema.prisma (updated)
## Decisions Made
1. Task entity uses UUID primary key
2. Soft delete pattern with deleted_at column
3. Status enum: TODO, IN_PROGRESS, DONE
## Open Questions
- Should task have project relationship now or later?
- Pagination: offset or cursor-based?
## Next Session
- Create TaskController
- Add API routes
- Write integration tests3. 맥락이 있는 새로운 세션
프롬프트 - 이전 세션 재개
Riprendo il lavoro su TaskFlow dopo una pausa.
## CONTESTO
[Incolla sezione rilevante da CLAUDE.md]
## ULTIMA SESSIONE
- Ho completato TaskService e TaskRepository
- Il database schema è aggiornato
- Mancano controller e route
## OGGI VOGLIO
1. Creare TaskController con tutti gli endpoint
2. Definire le route in Express
3. Scrivere test di integrazione
Prima di iniziare, vuoi che ti mostri il codice
del service per avere contesto?다중 저장소 관리
별도의 리포지토리로 작업해야 하는 경우 일관성을 유지하는 방법은 다음과 같습니다.
다중 저장소용 CLAUDE.md
CLAUDE.md 다중 저장소 구조
# CLAUDE.md - Frontend Repository
## This Repository
Frontend application for TaskFlow.
This is ONE of multiple repos that make up the project.
## Related Repositories
- **Backend:** github.com/user/taskflow-backend
- **Shared Types:** github.com/user/taskflow-shared
## Cross-Repository Contracts
### API Base URL
Development: http://localhost:3000/api/v1
Production: https://api.taskflow.com/v1
### Authentication
- JWT in Authorization header
- Format: `Bearer {{ '{' }}token{{ '}' }}`
- Refresh via POST /auth/refresh
### Type Sharing
We use `@taskflow/shared-types` npm package.
Types are source of truth - generated from backend OpenAPI spec.
## When Making Changes That Affect Other Repos
1. Update shared-types first
2. Publish new version
3. Update both FE and BE
4. Test integration locally프로젝트 설정 체크리스트
체크리스트: 최적의 컨텍스트
- 명확한 구조로 생성된 저장소
- 루트에서 CLAUDE.md를 완료하세요.
- 프로젝트 개요가 포함된 README.md
- 구성된 시스템 프롬프트(Claude.ai 프로젝트를 사용하는 경우)
- 프로젝트에 추가된 지식 파일
- 문서화된 명명 규칙
- 필수 변수가 포함된 .env.example 파일
- 로컬 개발을 위한 docker-compose.yml
- 일반적인 명령을 위한 npm 스크립트
컨텍스트 관리의 일반적인 실수
피해야 할 실수
- 컨텍스트가 너무 깁니다. 200,000개의 토큰은 많은 것 같지만 부족합니다. CLAUDE.md를 간결하고 집중적으로 유지하세요.
- 상충되는 정보: 규칙을 업데이트하는 경우 업데이트하세요. 또한 CLAUDE.md. 일관되지 않은 컨텍스트는 일관되지 않은 코드를 생성합니다.
- Knowledge에 파일이 너무 많습니다. 클로드는 모든 것을 읽습니다. 파일을 포함하는 경우 관련성이 없으면 중요한 부분에 대한 관심을 희석시킵니다.
- 체크포인트 없음: 요약이 없는 긴 세션이 이어집니다. 표류와 불일치.
- 일반 시스템 프롬프트: "당신은 숙련된 개발자입니다"만으로는 충분하지 않습니다. 스택과 기본 설정을 구체적으로 설명하세요.
결론
잘 구조화된 컨텍스트는 일관된 결과를 달성하는 데 중요합니다. Claude의 고품질. CLAUDE.md 생성에 시간을 투자하세요 그리고 저장소 구조에서: 이 투자는 성과를 거두었습니다. 모든 후속 상호 작용에서.
핵심 사항
- CLAUDE.md는 필수적입니다: 이 파일을 생성하고 업데이트된 상태로 유지하세요
- 저장소 구조 지우기: 클로드가 프로젝트를 탐색하도록 도와주세요
- 일관된 규칙: 예측 가능한 이름 지정으로 예측 가능한 코드 생성
- 정기 체크포인트: 긴 세션에서 컨텍스트 유지
- 개인 프로젝트를 위한 모노 저장소: 컨텍스트 관리 단순화
다음 기사
다음 기사에서 "개념 및 요구 사항" 우리는 방법을 볼 것이다 모호한 아이디어에서 구체적인 요구 사항으로 이동하려면 Claude를 사용하세요. MVP 정의, 사용자 페르소나, 사용 사례 및 기능 우선순위.