Copilot을 통한 전문 문서화
문서화는 종종 소프트웨어 개발에서 가장 간과되는 측면이지만, 유지 관리 및 새로운 개발자 온보딩에 매우 중요합니다. 문서 잘 작성하면 디버깅과 혼란에 드는 시간을 절약할 수 있습니다. GitHub Copilot을 사용하여 다음을 작성하세요. 전문적인 문서화가 빠르고 체계화됩니다.
이 문서에서는 Copilot을 사용하여 생성하는 방법을 살펴보겠습니다. 전문적인 README, OpenAPI를 사용한 API 문서, 아키텍처 결정 기록, JSDocs 완성 e 변경 내역 잘 구조화되어 있습니다.
📚 시리즈 개요
| # | Articolo | 집중하다 |
|---|---|---|
| 1 | 기초와 사고방식 | 설정과 사고방식 |
| 2 | 개념 및 요구사항 | 아이디어에서 MVP까지 |
| 3 | 백엔드 아키텍처 | API 및 데이터베이스 |
| 4 | 프런트엔드 구조 | UI 및 구성요소 |
| 5 | 신속한 엔지니어링 | MCP 프롬프트 및 에이전트 |
| 6 | 테스트 및 품질 | 단위, 통합, E2E |
| 7 | 📍 현재 위치 → 문서 | 읽어보기, API 문서, ADR |
| 8 | 배포 및 DevOps | 도커, CI/CD |
| 9 | 진화 | 확장성 및 유지 관리 |
문서 유형
전문적인 프로젝트에는 각각 특정 목적을 지닌 다양한 유형의 문서가 필요합니다.
📄 문서 지도
| 유형 | 청중 | 범위 | 업데이트 빈도 |
|---|---|---|---|
| 읽어보기.md | 모든 사람 | 첫인상, 빠른 시작 | 모든 주요 릴리스 |
| API 문서 | API 개발자 | 엔드포인트 참조 | 모든 API 변경 |
| ADR | 기술팀 | 아키텍처 결정 | 결정으로 |
| JSDoc/TSDoc | 개발자 | 코드 참조 | 코드로 |
| 변경 로그 | 사용자/개발자 | 변경 내역 | 모든 릴리스 |
| 기여 | 기여자 | 기여하는 방법 | 드물게 |
| 런북 | 운영 | 운영 절차 | 그들이 바뀔 때 |
읽어보기 전문가
README는 방문자가 가장 먼저 보게 되는 것입니다. 빨리 소통해야지 프로젝트의 내용, 사용 방법 및 기여 방법.
README 완료 프롬프트
프롬프트 - 전문적인 README 생성
Create a professional README.md for my project:
PROJECT INFO:
- Name: TaskFlow
- Type: SaaS task management for freelancers
- Stack: Node.js 20, Express 5, TypeScript 5.3, PostgreSQL 16, Angular 17
- Status: Beta (production-ready)
- License: MIT
FEATURES:
1. Project and task management with drag-and-drop
2. Time tracking with automatic reminders
3. Invoice generation from tracked time
4. Team collaboration (up to 5 users)
5. Integrations: Slack, Google Calendar, Stripe
SECTIONS TO INCLUDE:
1. Project title with logo placeholder and badges
2. One-paragraph description (compelling, benefit-focused)
3. Screenshots/demo section
4. Key features list with icons
5. Tech stack with version badges
6. Prerequisites
7. Installation (step-by-step, copy-pasteable)
8. Configuration (environment variables table)
9. Usage examples with code
10. API documentation link
11. Testing instructions
12. Deployment guide
13. Contributing guidelines
14. Roadmap (future features)
15. License
16. Contact/support info
STYLE:
- Use emojis sparingly for visual hierarchy
- Include copy-paste ready commands
- Add collapsible sections for detailed content
- Include badges from shields.io완전한 README 템플릿
README.md - 전문 템플릿
# TaskFlow
<p align="center">
<img src="docs/images/logo.png" alt="TaskFlow Logo" width="200">
</p>
<p align="center">
<strong>The smart task management platform for freelancers</strong>
</p>
<p align="center">
<a href="#features">Features</a> •
<a href="#quick-start">Quick Start</a> •
<a href="#documentation">Documentation</a> •
<a href="#contributing">Contributing</a>
</p>
<p align="center">
<img src="https://img.shields.io/badge/version-1.0.0-blue" alt="Version">
<img src="https://img.shields.io/badge/license-MIT-green" alt="License">
<img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build">
<img src="https://img.shields.io/badge/coverage-87%25-yellow" alt="Coverage">
<img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node">
</p>
---
## Overview
TaskFlow helps freelancers and small teams manage projects, track time,
and generate invoices - all in one place. Stop juggling multiple tools
and focus on what matters: delivering great work.
<p align="center">
<img src="docs/images/screenshot-dashboard.png" alt="Dashboard" width="80%">
</p>
## Features
| Feature | Description |
|---------|-------------|
| 📋 **Task Management** | Kanban boards, lists, and calendar views |
| ⏱️ **Time Tracking** | One-click timer with automatic reminders |
| 💰 **Invoicing** | Generate professional invoices from tracked time |
| 👥 **Team Collaboration** | Real-time sync for teams up to 5 members |
| 🔗 **Integrations** | Slack, Google Calendar, Stripe |
| 📊 **Analytics** | Weekly reports and productivity insights |
## Tech Stack
| Layer | Technology |
|-------|------------|
| **Backend** | Node.js 20, Express 5, TypeScript 5.3 |
| **Database** | PostgreSQL 16, Prisma ORM |
| **Frontend** | Angular 17, Tailwind CSS |
| **Auth** | JWT, OAuth 2.0 (Google, GitHub) |
| **Cache** | Redis 7 |
| **Queue** | BullMQ |
| **Testing** | Jest, Supertest, Playwright |
## Quick Start
### Prerequisites
- Node.js >= 20
- PostgreSQL >= 15
- Redis >= 7
- npm >= 10
### Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/taskflow.git
cd taskflow
# Install dependencies
npm install
# Copy environment file
cp .env.example .env
# Edit .env with your configuration (see Configuration section)
# Run database migrations
npm run db:migrate
# Seed initial data (optional)
npm run db:seed
# Start development server
npm run dev
```
The application will be available at `http://localhost:3000`.
## Configuration
Create a `.env` file based on `.env.example`:
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `NODE_ENV` | Environment (development/production) | Yes | development |
| `PORT` | Server port | No | 3000 |
| `DATABASE_URL` | PostgreSQL connection string | Yes | - |
| `REDIS_URL` | Redis connection string | Yes | - |
| `JWT_SECRET` | Secret for JWT signing (min 32 chars) | Yes | - |
| `JWT_EXPIRES_IN` | Token expiration | No | 7d |
| `GOOGLE_CLIENT_ID` | Google OAuth client ID | No | - |
| `STRIPE_SECRET_KEY` | Stripe API key | No | - |
<details>
<summary>📋 Full environment variables list</summary>
```env
# Server
NODE_ENV=development
PORT=3000
API_PREFIX=/api/v1
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/taskflow
# Redis
REDIS_URL=redis://localhost:6379
# Authentication
JWT_SECRET=your-super-secret-key-at-least-32-characters
JWT_EXPIRES_IN=7d
REFRESH_TOKEN_EXPIRES_IN=30d
# OAuth (optional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
# Email (optional)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=
SMTP_PASS=
# Stripe (optional)
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
```
</details>
## Usage
### Creating a Project
```bash
curl -X POST http://localhost:3000/api/v1/projects \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{{ "{" }}"name": "Website Redesign", "description": "Client project"{{ "}" }}'
```
### Starting Time Tracking
```bash
curl -X POST http://localhost:3000/api/v1/time-entries/start \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{{ "{" }}"taskId": "task-123"{{ "}" }}'
```
See [API Documentation](docs/API.md) for complete reference.
## Testing
```bash
# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Run specific test suite
npm test -- --grep "UserService"
# Run E2E tests
npm run test:e2e
```
## Deployment
See [Deployment Guide](docs/DEPLOYMENT.md) for detailed instructions.
### Quick Deploy with Docker
```bash
# Build image
docker build -t taskflow:latest .
# Run with docker-compose
docker-compose up -d
```
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Roadmap
- [x] Core task management
- [x] Time tracking
- [x] Basic invoicing
- [ ] Mobile app (React Native)
- [ ] AI-powered task suggestions
- [ ] Advanced reporting
- [ ] Zapier integration
## License
This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.
## Support
- 📖 [Documentation](https://docs.taskflow.dev)
- 💬 [Discord Community](https://discord.gg/taskflow)
- 🐛 [Issue Tracker](https://github.com/yourusername/taskflow/issues)
- 📧 [Email Support](mailto:support@taskflow.dev)
---
<p align="center">
Made with ❤️ by <a href="https://github.com/yourusername">Your Name</a>
</p>OpenAPI를 사용한 API 문서
API 문서는 가능할 때마다 코드에서 자동으로 생성되어야 합니다. 그러나 Copilot은 초기 OpenAPI 사양을 작성하거나 이를 강화하는 데 도움을 줄 수 있습니다.
OpenAPI 사양에 대한 프롬프트
프롬프트 - OpenAPI 사양 생성
Generate OpenAPI 3.1 specification for these endpoints:
RESOURCE: Tasks
BASE PATH: /api/v1/tasks
ENDPOINTS:
1. POST /tasks - Create task
2. GET /tasks - List tasks (paginated, filterable)
3. GET /tasks/:id - Get task by ID
4. PATCH /tasks/:id - Update task
5. DELETE /tasks/:id - Delete task
6. POST /tasks/:id/start - Start time tracking
7. POST /tasks/:id/stop - Stop time tracking
TASK SCHEMA:
- id: UUID (readonly)
- title: string (required, 3-200 chars)
- description: string (optional, max 5000)
- status: enum [todo, in_progress, done]
- priority: enum [low, medium, high]
- dueDate: ISO8601 datetime (optional)
- projectId: UUID (required)
- assigneeId: UUID (optional)
- estimatedHours: number (optional)
- actualHours: number (readonly, computed)
- createdAt: datetime (readonly)
- updatedAt: datetime (readonly)
INCLUDE:
- Complete request/response schemas
- All query parameters for list endpoint
- Authentication (Bearer token)
- Error responses (400, 401, 403, 404, 500)
- Example values for all fields
- Descriptions in Italian for public docsOpenAPI 예제 완료
YAML - openapi.yaml(작업 리소스)
openapi: 3.1.0
info:
title: TaskFlow API
description: |
API per la gestione di task e progetti.
## Autenticazione
Tutte le richieste richiedono un token JWT nel header Authorization:
```
Authorization: Bearer <token>
```
## Rate Limiting
- 100 richieste/minuto per utente autenticato
- 10 richieste/minuto per IP non autenticato
version: 1.0.0
contact:
email: api@taskflow.dev
servers:
- url: https://api.taskflow.dev/v1
description: Production
- url: https://staging-api.taskflow.dev/v1
description: Staging
- url: http://localhost:3000/api/v1
description: Local Development
tags:
- name: Tasks
description: Gestione dei task
paths:
/tasks:
post:
tags: [Tasks]
summary: Crea un nuovo task
description: Crea un task associato a un progetto.
operationId: createTask
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTaskRequest'
example:
title: "Implementare login OAuth"
description: "Aggiungere supporto per Google e GitHub OAuth"
projectId: "proj-123"
priority: "high"
dueDate: "2025-02-15T10:00:00Z"
responses:
'201':
description: Task creato con successo
content:
application/json:
schema:
$ref: '#/components/schemas/TaskResponse'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
get:
tags: [Tasks]
summary: Lista dei task
description: |
Recupera una lista paginata di task con filtri opzionali.
I risultati sono ordinati per data di creazione decrescente.
operationId: listTasks
security:
- bearerAuth: []
parameters:
- name: page
in: query
description: Numero pagina (1-based)
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
description: Elementi per pagina
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: projectId
in: query
description: Filtra per progetto
schema:
type: string
format: uuid
- name: status
in: query
description: Filtra per stato
schema:
type: string
enum: [todo, in_progress, done]
- name: priority
in: query
description: Filtra per priorità
schema:
type: string
enum: [low, medium, high]
- name: assigneeId
in: query
description: Filtra per assegnatario
schema:
type: string
format: uuid
- name: search
in: query
description: Cerca nel titolo e descrizione
schema:
type: string
minLength: 2
responses:
'200':
description: Lista task
content:
application/json:
schema:
$ref: '#/components/schemas/TaskListResponse'
/tasks/{{ '{' }}taskId{{ '}' }}:
parameters:
- name: taskId
in: path
required: true
description: ID univoco del task
schema:
type: string
format: uuid
get:
tags: [Tasks]
summary: Dettaglio task
operationId: getTask
security:
- bearerAuth: []
responses:
'200':
description: Task trovato
content:
application/json:
schema:
$ref: '#/components/schemas/TaskResponse'
'404':
$ref: '#/components/responses/NotFound'
patch:
tags: [Tasks]
summary: Aggiorna task
description: Aggiorna uno o più campi del task.
operationId: updateTask
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTaskRequest'
responses:
'200':
description: Task aggiornato
content:
application/json:
schema:
$ref: '#/components/schemas/TaskResponse'
'404':
$ref: '#/components/responses/NotFound'
delete:
tags: [Tasks]
summary: Elimina task
description: Soft delete - il task viene marcato come eliminato.
operationId: deleteTask
security:
- bearerAuth: []
responses:
'204':
description: Task eliminato
'404':
$ref: '#/components/responses/NotFound'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
CreateTaskRequest:
type: object
required: [title, projectId]
properties:
title:
type: string
minLength: 3
maxLength: 200
description: Titolo del task
description:
type: string
maxLength: 5000
description: Descrizione dettagliata
projectId:
type: string
format: uuid
description: ID del progetto
priority:
type: string
enum: [low, medium, high]
default: medium
status:
type: string
enum: [todo, in_progress, done]
default: todo
dueDate:
type: string
format: date-time
assigneeId:
type: string
format: uuid
estimatedHours:
type: number
minimum: 0
UpdateTaskRequest:
type: object
properties:
title:
type: string
minLength: 3
maxLength: 200
description:
type: string
maxLength: 5000
priority:
type: string
enum: [low, medium, high]
status:
type: string
enum: [todo, in_progress, done]
dueDate:
type: string
format: date-time
assigneeId:
type: string
format: uuid
Task:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
title:
type: string
description:
type: string
projectId:
type: string
format: uuid
status:
type: string
enum: [todo, in_progress, done]
priority:
type: string
enum: [low, medium, high]
dueDate:
type: string
format: date-time
assigneeId:
type: string
format: uuid
estimatedHours:
type: number
actualHours:
type: number
readOnly: true
createdAt:
type: string
format: date-time
readOnly: true
updatedAt:
type: string
format: date-time
readOnly: true
TaskResponse:
type: object
properties:
data:
$ref: '#/components/schemas/Task'
TaskListResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Task'
meta:
type: object
properties:
page:
type: integer
limit:
type: integer
total:
type: integer
totalPages:
type: integer
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: array
items:
type: object
properties:
field:
type: string
message:
type: string
responses:
ValidationError:
description: Errore di validazione
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: VALIDATION_ERROR
message: Dati non validi
details:
- field: title
message: Il titolo deve avere almeno 3 caratteri
Unauthorized:
description: Non autenticato
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: Token mancante o non valido
Forbidden:
description: Accesso negato
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: FORBIDDEN
message: Non hai i permessi per questa operazione
NotFound:
description: Risorsa non trovata
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: NOT_FOUND
message: Task non trovatoADR(아키텍처 결정 기록)
ADR은 중요한 아키텍처 결정, 즉 컨텍스트를 문서화합니다. 채택되었으며 대안이 고려되었습니다. 이해하는 데 필수적입니다. 기술적 선택의 "이유".
ADR 프롬프트
프롬프트 - ADR 생성
Create an Architecture Decision Record (ADR) for this decision:
DECISION: Usare PostgreSQL come database invece di MongoDB
CONTEXT: Stiamo costruendo un task management SaaS
DATE: 2025-01-30
FACTORS CONSIDERED:
1. Dati fortemente relazionali (users, projects, tasks, time entries)
2. Need for complex queries and reporting
3. ACID compliance for financial data (invoicing)
4. Team familiarity with SQL
5. Future scaling needs
ALTERNATIVES:
1. MongoDB - NoSQL, flexible schema
2. MySQL - Traditional RDBMS
3. CockroachDB - Distributed SQL
Follow the standard ADR template with:
- Title (ADR-XXX: Brief description)
- Status
- Context
- Decision
- Alternatives Considered (with pros/cons)
- Consequences (positive, negative, risks)
- Notes/Follow-up완전한 ADR 템플릿
docs/adr/ADR-001-database-postgresql.md
# ADR-001: Scelta di PostgreSQL come Database Primario
## Status
**Accepted** - 2025-01-30
## Context
Stiamo progettando il backend per TaskFlow, una piattaforma SaaS per la gestione
di task e progetti rivolta a freelancer e piccoli team. Il sistema deve gestire:
- **Utenti e team:** Relazioni N:M con ruoli e permessi
- **Progetti e task:** Struttura gerarchica, stati, priorità
- **Time tracking:** Sessioni di lavoro con timestamp precisi
- **Fatturazione:** Dati finanziari che richiedono precisione e audit trail
- **Analytics:** Query complesse per report e dashboard
### Requisiti chiave
1. **Integrità dei dati:** I dati finanziari richiedono transazioni ACID
2. **Query complesse:** Report che aggregano dati da multiple tabelle
3. **Scalabilità verticale:** MVP con 1000 utenti, target 50.000 in 18 mesi
4. **Performance:** Dashboard deve caricare in <500ms
5. **Costo:** Budget limitato per infrastruttura
### Vincoli
- Team di 2 sviluppatori con esperienza SQL
- Timeline MVP: 3 mesi
- Hosting cloud (preferibilmente managed)
## Decision
Utilizziamo **PostgreSQL 16** come database primario, con **Prisma ORM** per l'accesso dati.
### Motivazioni
1. **Modello relazionale:** I nostri dati sono fortemente relazionali (users → projects → tasks → time_entries)
2. **ACID compliance:** Transazioni atomiche per operazioni finanziarie
3. **Query potenti:** JOIN, aggregazioni, window functions per analytics
4. **JSONB:** Flessibilità per metadati senza sacrificare la struttura
5. **Maturità:** 30+ anni di sviluppo, documentazione eccellente, community attiva
6. **Tooling:** Prisma ha supporto first-class, pgAdmin per admin, pg_dump per backup
7. **Managed options:** Disponibile su tutti i cloud provider (Supabase, Neon, RDS)
## Alternatives Considered
### MongoDB
| Aspect | Pro | Contro |
|--------|-----|--------|
| Schema | Flessibile, evolve facilmente | Meno controllo integrità |
| Query | Semplici su singoli documenti | JOIN costose (lookup) |
| Scale | Horizontal scaling nativo | Overkill per le nostre esigenze |
| Team | - | Nessuna esperienza |
| Cost | - | Atlas costoso per feature enterprise |
**Decisione:** Scartato. I nostri dati sono relazionali, MongoDB aggiungerebbe complessità inutile.
### MySQL 8
| Aspect | Pro | Contro |
|--------|-----|--------|
| Familiarità | Molto diffuso | Supporto JSON meno maturo |
| Performance | Buona per OLTP | Window functions più limitate |
| Cost | Economico | - |
| Tooling | Prisma supporta | - |
**Decisione:** Valida alternativa, ma PostgreSQL offre feature più avanzate (JSONB, array, full-text search nativo).
### CockroachDB
| Aspect | Pro | Contro |
|--------|-----|--------|
| Scale | Distributed di default | Complessità operativa |
| Resilience | Multi-region built-in | Overkill per MVP |
| Compatibility | PostgreSQL wire protocol | Alcune differenze |
| Cost | - | Tier gratuito limitato |
**Decisione:** Scartato per MVP. Potrebbe essere considerato per scale-up futuro.
## Consequences
### Positive
1. **Query potenti:** Possiamo costruire analytics complesse senza caching layer
2. **Integrità garantita:** Foreign keys, constraints, transazioni
3. **Developer experience:** Prisma migrations, type safety
4. **Ecosistema:** Estensioni (PostGIS se servirà geo), pgvector per AI
5. **Costo prevedibile:** Managed PostgreSQL a prezzi ragionevoli
### Negative
1. **Scaling orizzontale:** Richiede più lavoro (read replicas, sharding manuale)
2. **Schema rigido:** Migrazioni necessarie per modifiche strutturali
3. **Vendor lock-in:** Alcune feature PG-specific (JSONB operators)
### Risks
| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| Performance issues at scale | Medium | High | Monitoring, query optimization, read replicas |
| Vendor lock-in | Low | Medium | Usare SQL standard dove possibile |
| Team learning curve | Low | Low | Documentazione interna, pair programming |
## Implementation Notes
### Hosting
- **Development:** Docker locale
- **Staging:** Supabase (tier gratuito)
- **Production:** Supabase Pro o Neon (da valutare costi)
### Backup Strategy
- Point-in-time recovery abilitato
- Daily snapshots automatici
- Test restore mensile
### Monitoring
- Query performance con pg_stat_statements
- Connection pooling con PgBouncer
- Alerting su slow queries (>1s)
## Follow-up Actions
- [ ] Setup Prisma con PostgreSQL
- [ ] Configurare docker-compose per development
- [ ] Definire schema iniziale per User, Project, Task
- [ ] Creare monitoring dashboard
## Related Decisions
- ADR-002: Scelta ORM (Prisma)
- ADR-003: Caching strategy (Redis)
## References
- [PostgreSQL vs MongoDB 2025](https://example.com/comparison)
- [Prisma PostgreSQL Guide](https://www.prisma.io/docs/concepts/database-connectors/postgresql)
- [Supabase Pricing](https://supabase.com/pricing)
---
**Author:** Federico Calò
**Reviewers:** Team Lead
**Last Updated:** 2025-01-30JSDoc 및 코드 문서
인라인 문서는 개발자가 별도의 작업 없이 코드를 이해하는 데 도움이 됩니다. 전체 구현을 읽어야합니다.
JSDoc에 대한 프롬프트
프롬프트 - JSDoc 문서 추가
Add comprehensive JSDoc documentation to this TypeScript code:
```typescript
[PASTE CODE HERE]
```
INCLUDE FOR EACH FUNCTION/METHOD:
1. Brief description (one sentence)
2. Detailed explanation (if complex)
3. @param for each parameter with type and description
4. @returns with type and description
5. @throws for each exception that can be thrown
6. @example with realistic usage
7. @see for related functions
8. @since version number
9. @deprecated if applicable
STYLE:
- Use imperative mood ("Creates a user" not "This creates a user")
- Document edge cases in description
- Include validation rules in @param descriptions
- Add @remarks for implementation notes완전한 JSDoc 예제
TypeScript - 문서화된 서비스
/**
* Service per la gestione degli utenti.
*
* Gestisce operazioni CRUD, autenticazione e autorizzazione per gli utenti.
* Tutte le password sono hashate con bcrypt prima del salvataggio.
*
* @remarks
* Questo service non gestisce direttamente i token JWT. Vedi {@link AuthService}
* per le operazioni di autenticazione.
*
* @example
* ```typescript
* const userService = new UserService(userRepository, emailService);
*
* // Creare un nuovo utente
* const user = await userService.create({
* name: 'Mario Rossi',
* email: 'mario@example.com',
* password: 'SecurePass123!'
* });
*
* // Aggiornare un utente
* await userService.update(user.id, { name: 'Mario Bianchi' });
* ```
*
* @since 1.0.0
*/
export class UserService {
/**
* Crea una nuova istanza di UserService.
*
* @param userRepository - Repository per l'accesso ai dati utente
* @param emailService - Service per l'invio di email
*/
constructor(
private readonly userRepository: UserRepository,
private readonly emailService: EmailService
) {}
/**
* Crea un nuovo utente nel sistema.
*
* Valida i dati in input, verifica che l'email non sia già registrata,
* hash della password e invio email di benvenuto.
*
* @param dto - Dati per la creazione dell'utente
* @param dto.name - Nome completo (2-100 caratteri)
* @param dto.email - Email valida e unica nel sistema
* @param dto.password - Password (min 8 char, 1 maiuscola, 1 numero, 1 speciale)
*
* @returns L'utente creato (senza password)
*
* @throws {ValidationError} Se i dati non superano la validazione
* @throws {ConflictError} Se l'email è già registrata
* @throws {ServiceError} Se l'invio email fallisce (utente creato comunque)
*
* @example
* ```typescript
* try {
* const user = await userService.create({
* name: 'Mario Rossi',
* email: 'mario@example.com',
* password: 'SecurePass123!'
* });
* console.log(`Utente creato: ${user.id}`);
* } catch (error) {
* if (error instanceof ConflictError) {
* console.error('Email già registrata');
* }
* }
* ```
*
* @see {@link UserService.update} per aggiornare un utente esistente
* @since 1.0.0
*/
async create(dto: CreateUserDto): Promise<User> {
// Implementation...
}
/**
* Recupera un utente per ID.
*
* @param id - UUID dell'utente
*
* @returns L'utente trovato
*
* @throws {ValidationError} Se l'ID non è un UUID valido
* @throws {NotFoundError} Se l'utente non esiste o è stato eliminato
*
* @example
* ```typescript
* const user = await userService.findById('550e8400-e29b-41d4-a716-446655440000');
* ```
*
* @since 1.0.0
*/
async findById(id: string): Promise<User> {
// Implementation...
}
/**
* Aggiorna un utente esistente.
*
* Aggiorna solo i campi forniti. I campi non inclusi nel DTO rimangono invariati.
*
* @param id - UUID dell'utente da aggiornare
* @param dto - Campi da aggiornare (tutti opzionali)
* @param dto.name - Nuovo nome (2-100 caratteri)
* @param dto.email - Nuova email (deve essere unica)
* @param dto.password - Nuova password (verrà hashata)
*
* @returns L'utente aggiornato
*
* @throws {NotFoundError} Se l'utente non esiste
* @throws {ConflictError} Se la nuova email è già in uso da un altro utente
* @throws {ValidationError} Se i dati non superano la validazione
*
* @remarks
* L'aggiornamento dell'email non richiede verifica email. Per implementazioni
* più sicure, considerare un flusso di verifica separato.
*
* @example
* ```typescript
* // Aggiorna solo il nome
* const updated = await userService.update(userId, { name: 'Nuovo Nome' });
*
* // Aggiorna più campi
* const updated = await userService.update(userId, {
* name: 'Nuovo Nome',
* email: 'nuova@email.com'
* });
* ```
*
* @since 1.0.0
*/
async update(id: string, dto: UpdateUserDto): Promise<User> {
// Implementation...
}
/**
* Elimina un utente (soft delete).
*
* L'utente viene marcato come eliminato ma i dati vengono mantenuti per
* audit e compliance. Non è possibile fare login dopo la soft delete.
*
* @param id - UUID dell'utente da eliminare
*
* @throws {NotFoundError} Se l'utente non esiste
* @throws {ForbiddenError} Se si tenta di eliminare l'ultimo admin
*
* @remarks
* Per eliminare definitivamente i dati (GDPR), usare {@link hardDelete}.
*
* @example
* ```typescript
* await userService.softDelete(userId);
* // L'utente non può più fare login
* ```
*
* @see {@link UserService.hardDelete} per eliminazione definitiva
* @since 1.0.0
*/
async softDelete(id: string): Promise<void> {
// Implementation...
}
}변경 내역
잘 구성된 변경 로그는 릴리스 간에 변경된 내용을 명확하게 전달합니다. "변경 로그 유지" 형식을 따릅니다.
변경 로그 프롬프트
프롬프트 - 변경 로그 항목 생성
Generate a changelog entry for version 1.2.0.
CHANGES MADE:
1. Added email notification system for task deadlines
2. Added user preferences page
3. Fixed bug where tasks could be duplicated when clicking save twice
4. Fixed memory leak in websocket connections
5. Improved task filtering performance (50% faster)
6. Updated error messages for better UX
7. Removed deprecated v1 API endpoints
Follow Keep a Changelog format with sections:
- Added (new features)
- Changed (changes in existing functionality)
- Deprecated (features that will be removed)
- Removed (removed features)
- Fixed (bug fixes)
- Security (security fixes)예 CHANGELOG.md
변경 로그.md
# Changelog
All notable changes to TaskFlow will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- Dark mode support (#234)
- Keyboard shortcuts for common actions
### Changed
- Improved onboarding flow
---
## [1.2.0] - 2025-02-01
### Added
- **Email notifications** for task deadlines - Users now receive email reminders
24 hours and 1 hour before task due dates
- **User preferences page** - Customize notification settings, timezone, and language
- Export tasks to CSV format
### Changed
- Improved task filtering performance by 50% through database query optimization
- Updated error messages to be more user-friendly and actionable
- Redesigned task card layout for better information density
### Fixed
- Fixed bug where tasks could be duplicated when clicking save button rapidly (#187)
- Fixed memory leak in websocket connections that caused browser slowdown (#192)
- Fixed timezone handling in due date display (#195)
### Removed
- Removed deprecated v1 API endpoints (deprecated in 1.0.0)
---
## [1.1.0] - 2025-01-15
### Added
- **Task labels and categories** - Organize tasks with custom colored labels
- **Export to CSV** - Download task data for external analysis
- Bulk task operations (archive, delete, move)
### Changed
- Increased maximum task description length from 2000 to 5000 characters
- Improved mobile responsiveness of kanban board
### Fixed
- Fixed issue where completed tasks weren't syncing across devices (#156)
- Fixed search not finding tasks with special characters (#161)
### Security
- Updated dependencies to patch CVE-2025-1234 in express-validator
---
## [1.0.0] - 2025-01-01
### Added
- Initial release
- User authentication (email/password, Google OAuth)
- Project management with team collaboration
- Task management with drag-and-drop kanban board
- Time tracking with one-click timer
- Basic reporting dashboard
---
[Unreleased]: https://github.com/username/taskflow/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/username/taskflow/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/username/taskflow/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/username/taskflow/releases/tag/v1.0.0문서화 모범 사례
❌ 흔히 저지르는 실수
- 오래된 문서
- 미니멀리스트 README
- 코드 예시 없음
- 기술 문서만
- 맥락 부족
- 영어로만 작성된 문서
- 변경 내역 없음
- 누락된 ADR
✅ 모범 사례
- 코드로 문서 업데이트
- 완전하고 환영받는 README
- 복사-붙여넣기 준비 예시
- 다양한 역할에 대한 문서
- "이유"를 설명하세요.
- 문서는 언어로 사용자를 대상으로 합니다.
- 각 릴리스에 대한 변경 로그
- 중요한 결정을 위한 ADR
문서화 체크리스트
✅ 출시 전
- ☐ 새로운 기능으로 업데이트된 README
- ☐ API 문서는 현재 엔드포인트를 반영합니다.
- ☐ 버전에 대한 변경 로그 항목
- ☐ 새로운 공개 기능을 위한 JSDoc
- ☐ 테스트되고 작동하는 예제
- ☐ 확인된 링크 및 참고자료
- ☐ 업데이트된 스크린샷(UI가 변경된 경우)
- ☐ 문서화된 환경 변수
- ☐ 주요 변경 사항이 강조 표시됨
- ☐ 마이그레이션 가이드(필요한 경우)
결론 및 다음 단계
문서화는 시간이 지나면서 엄청난 이익을 얻을 수 있는 투자입니다. 온보딩 시간 단축, 반복적인 질문 감소, 수익 증대 가장 전문적이고 신뢰할 수 있는 프로젝트입니다.
Copilot은 고품질의 초안을 생성할 수 있지만 내용 검증하고 맞춤화해야 합니다.. AI는 세부사항을 모른다 귀하의 프로젝트에 따라 다릅니다.
에서 다음 기사 Copilot을 사용하는 방법을 살펴보겠습니다. 배포 및 DevOps: Dockerfile 다단계, Docker Compose, GitHub Actions, 상태 확인 및 프로덕션 로깅이 포함된 CI/CD.
🎯 기억해야 할 핵심 사항
- 읽어보기: 첫인상 – 완전하고 환영받는 분위기로 만드세요
- 오픈API: 생성 및 테스트 가능한 API 문서
- ADR: 아키텍처 결정의 "이유"를 문서화합니다.
- JSDoc: 개발자를 위한 인라인 문서
- 변경 내역: 사용자 및 개발자의 변경 기록
- 업데이트: 문서는 코드와 함께 발전해야 합니다.
- 확인하다: Copilot이 생성하는 내용을 항상 확인하세요.