Copilot による専門的なドキュメント
ドキュメントはソフトウェア開発において最も見落とされがちな側面ですが、それでもなお、 保守性と新しい開発者のオンボーディングにとって重要です。ドキュメント 適切に記述しておけば、何時間ものデバッグや混乱を避けることができます。 GitHub Copilot を使用して、次のように書きます。 専門的な文書が迅速かつ体系的に作成されます。
この記事では、Copilot を使用して 専門的な README, OpenAPI を使用した API ドキュメント, アーキテクチャの決定記録, 完全な JSDoc e 変更履歴 よく構造化されている。
📚 シリーズ概要
| # | アイテム | 集中 |
|---|---|---|
| 1 | 基礎と考え方 | セットアップとメンタリティ |
| 2 | コンセプトと要件 | アイデアから MVP まで |
| 3 | バックエンドのアーキテクチャ | APIとデータベース |
| 4 | フロントエンドの構造 | UIとコンポーネント |
| 5 | 迅速なエンジニアリング | MCP プロンプトとエージェント |
| 6 | テストと品質 | ユニット、統合、E2E |
| 7 | 📍 現在ここにいます → ドキュメント | README、API ドキュメント、ADR |
| 8 | デプロイとDevOps | ドッカー、CI/CD |
| 9 | 進化 | スケーラビリティとメンテナンス |
文書の種類
専門的なプロジェクトには、それぞれ特定の目的を持つさまざまな種類の文書が必要です。
📄 ドキュメントマップ
| タイプ | 観客 | 範囲 | 更新頻度 |
|---|---|---|---|
| README.md | みんな | 第一印象、クイックスタート | メジャーリリースごとに |
| APIドキュメント | API開発者 | エンドポイントリファレンス | API の変更 |
| ADR | 技術チーム | アーキテクチャ上の決定 | 決定により |
| JSDoc/TSDoc | 開発者 | コードリファレンス | コード付き |
| 変更履歴 | ユーザー/開発者 | 変更履歴 | リリースごとに |
| 貢献する | 貢献者 | 貢献方法 | めったに |
| ランブック | 運営 | 操作手順 | 彼らが変わるとき |
README プロフェッショナル
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 docs完全な OpenAPI の例
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 trovatoアーキテクチャ決定記録 (ADR)
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...
}
}変更履歴
A well-structured changelog clearly communicates what has changed between releases. 「変更履歴を残す」形式に従います。
変更ログのプロンプト
プロンプト - 変更ログエントリの生成
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には詳細は分からない あなたのプロジェクトに特有のものです - あなたはそうします。
Nel 次の記事 Copilot の使用方法を見ていきます。 導入とDevOps: Dockerfileマルチステージ、Docker Compose、 GitHub Actions、ヘルスチェック、本番ログを使用した CI/CD。
🎯 覚えておくべき重要なポイント
- お読みください: 第一印象 - 完成度が高く、歓迎されるものにする
- オープンAPI: 生成およびテスト可能な API ドキュメント
- ADR: アーキテクチャ上の決定の「理由」を文書化する
- JSDoc: 開発者向けのインラインドキュメント
- 変更履歴: ユーザーと開発者の変更履歴
- アップデート： ドキュメントはコードとともに進化する必要がある
- 確認する： Copilot が生成するものを常に確認してください