mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
refactor: optimize workflow templates and prompt structures
- Streamlined analysis templates (architecture, pattern, performance, quality, security) - Simplified development templates (component, debugging, feature, refactor, testing) - Optimized documentation templates (api, folder-navigation, module-readme, project-architecture, project-examples, project-readme) - Enhanced planning templates (concept-eval, migration, task-breakdown) - Improved verification templates (codex-technical, cross-validation, gemini-strategic) - Updated claude-module-unified memory template - Refined workflow-architecture documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -1,337 +1,15 @@
|
||||
# Unified API Documentation Template
|
||||
Generate comprehensive API documentation for code or HTTP services.
|
||||
|
||||
Generate comprehensive API documentation. This template supports both **Code API** (for libraries/modules) and **HTTP API** (for web services). Include only the sections relevant to your project type.
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Include only sections relevant to the project type (Code API vs. HTTP API)
|
||||
□ Provide complete and runnable examples for HTTP APIs
|
||||
□ Use signatures-only for Code API documentation (no implementation)
|
||||
□ Document all public-facing APIs, not internal ones
|
||||
|
||||
---
|
||||
## UNIFIED API DOCUMENTATION TEMPLATE
|
||||
|
||||
## Part A: Code API (For Libraries, Modules, SDKs)
|
||||
This template supports both **Code API** (for libraries/modules) and **HTTP API** (for web services). Include only the sections relevant to your project type.
|
||||
|
||||
**Use this section when documenting**: Exported functions, classes, interfaces, and types from code modules.
|
||||
---
|
||||
|
||||
**Omit this section if**: This is a pure web service with only HTTP endpoints and no programmatic API.
|
||||
|
||||
### 1. Exported Functions
|
||||
|
||||
For each exported function, provide:
|
||||
```typescript
|
||||
/**
|
||||
* Brief one-line description of what the function does
|
||||
* @param paramName - Parameter type and description
|
||||
* @returns Return type and description
|
||||
* @throws ErrorType - When this error occurs
|
||||
*/
|
||||
export function functionName(paramName: ParamType): ReturnType;
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```typescript
|
||||
/**
|
||||
* Authenticates a user with email and password
|
||||
* @param credentials - User email and password
|
||||
* @returns Authentication token and user info
|
||||
* @throws AuthenticationError - When credentials are invalid
|
||||
*/
|
||||
export function authenticate(credentials: Credentials): Promise<AuthResult>;
|
||||
```
|
||||
|
||||
### 2. Exported Classes
|
||||
|
||||
For each exported class, provide:
|
||||
```typescript
|
||||
/**
|
||||
* Brief one-line description of the class purpose
|
||||
*/
|
||||
export class ClassName {
|
||||
constructor(param: Type);
|
||||
|
||||
// Public properties
|
||||
propertyName: Type;
|
||||
|
||||
// Public methods
|
||||
methodName(param: Type): ReturnType;
|
||||
}
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```typescript
|
||||
/**
|
||||
* Manages user session lifecycle and token refresh
|
||||
*/
|
||||
export class SessionManager {
|
||||
constructor(config: SessionConfig);
|
||||
|
||||
// Current session state
|
||||
isActive: boolean;
|
||||
|
||||
// Refresh the session token
|
||||
refresh(): Promise<void>;
|
||||
|
||||
// Terminate the session
|
||||
destroy(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Exported Interfaces
|
||||
|
||||
For each exported interface, provide:
|
||||
```typescript
|
||||
/**
|
||||
* Brief description of what this interface represents
|
||||
*/
|
||||
export interface InterfaceName {
|
||||
field1: Type; // Field description
|
||||
field2: Type; // Field description
|
||||
method?: (param: Type) => ReturnType; // Optional method
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Type Definitions
|
||||
|
||||
For each exported type, provide:
|
||||
```typescript
|
||||
/**
|
||||
* Brief description of what this type represents
|
||||
*/
|
||||
export type TypeName = string | number | CustomType;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Part B: HTTP API (For Web Services, REST APIs, GraphQL)
|
||||
|
||||
**Use this section when documenting**: HTTP endpoints, REST APIs, GraphQL APIs, webhooks.
|
||||
|
||||
**Omit this section if**: This is a library/SDK with no HTTP interface.
|
||||
|
||||
### 1. Overview
|
||||
|
||||
[Brief description of the API's purpose and capabilities]
|
||||
|
||||
**Base URL**:
|
||||
```
|
||||
Production: https://api.example.com/v1
|
||||
Staging: https://staging.api.example.com/v1
|
||||
Development: http://localhost:3000/api/v1
|
||||
```
|
||||
|
||||
### 2. Authentication
|
||||
|
||||
#### Authentication Method
|
||||
[e.g., JWT Bearer Token, OAuth2, API Keys]
|
||||
|
||||
#### Obtaining Credentials
|
||||
```bash
|
||||
# Example: Login to get token
|
||||
curl -X POST https://api.example.com/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email": "user@example.com", "password": "password"}'
|
||||
```
|
||||
|
||||
#### Using Credentials
|
||||
```http
|
||||
GET /api/resource HTTP/1.1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 3. Common Response Codes
|
||||
|
||||
| Code | Description | Common Causes |
|
||||
|------|-------------|---------------|
|
||||
| 200 | Success | Request completed successfully |
|
||||
| 201 | Created | Resource created successfully |
|
||||
| 400 | Bad Request | Invalid request body or parameters |
|
||||
| 401 | Unauthorized | Missing or invalid authentication |
|
||||
| 403 | Forbidden | Authenticated but not authorized |
|
||||
| 404 | Not Found | Resource does not exist |
|
||||
| 429 | Too Many Requests | Rate limit exceeded |
|
||||
| 500 | Internal Server Error | Server-side error |
|
||||
|
||||
### 4. Endpoints
|
||||
|
||||
#### Resource: [Resource Name, e.g., Users]
|
||||
|
||||
##### GET /resource
|
||||
**Description**: [What this endpoint does]
|
||||
|
||||
**Query Parameters**:
|
||||
| Parameter | Type | Required | Description | Default |
|
||||
|-----------|------|----------|-------------|---------|
|
||||
| `limit` | number | No | Number of results | 20 |
|
||||
| `offset` | number | No | Pagination offset | 0 |
|
||||
|
||||
**Example Request**:
|
||||
```http
|
||||
GET /users?limit=10&offset=0 HTTP/1.1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Response (200 OK)**:
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "John Doe",
|
||||
"email": "john@example.com"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"total": 100,
|
||||
"limit": 10,
|
||||
"offset": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Error Response (401 Unauthorized)**:
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "UNAUTHORIZED",
|
||||
"message": "Invalid or expired token"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
##### POST /resource
|
||||
**Description**: [What this endpoint does]
|
||||
|
||||
**Request Body**:
|
||||
```json
|
||||
{
|
||||
"field1": "value",
|
||||
"field2": 123
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Rules**:
|
||||
- `field1`: Required, 2-100 characters
|
||||
- `field2`: Required, positive integer
|
||||
|
||||
**Response (201 Created)**:
|
||||
```json
|
||||
{
|
||||
"id": 124,
|
||||
"field1": "value",
|
||||
"field2": 123,
|
||||
"created_at": "2024-01-20T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
##### PUT /resource/:id
|
||||
**Description**: [What this endpoint does]
|
||||
|
||||
**Path Parameters**:
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `id` | number | Resource ID |
|
||||
|
||||
**Request Body** (all fields optional):
|
||||
```json
|
||||
{
|
||||
"field1": "new value"
|
||||
}
|
||||
```
|
||||
|
||||
**Response (200 OK)**:
|
||||
```json
|
||||
{
|
||||
"id": 124,
|
||||
"field1": "new value",
|
||||
"updated_at": "2024-01-21T09:15:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
##### DELETE /resource/:id
|
||||
**Description**: [What this endpoint does]
|
||||
|
||||
**Path Parameters**:
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `id` | number | Resource ID |
|
||||
|
||||
**Response (204 No Content)**:
|
||||
[Empty response body]
|
||||
|
||||
---
|
||||
|
||||
### 5. Rate Limiting
|
||||
|
||||
- **Limit**: 1000 requests per hour per API key
|
||||
- **Headers**:
|
||||
- `X-RateLimit-Limit`: Total requests allowed
|
||||
- `X-RateLimit-Remaining`: Requests remaining
|
||||
- `X-RateLimit-Reset`: Unix timestamp when limit resets
|
||||
|
||||
**Example Response Headers**:
|
||||
```http
|
||||
X-RateLimit-Limit: 1000
|
||||
X-RateLimit-Remaining: 847
|
||||
X-RateLimit-Reset: 1640000000
|
||||
```
|
||||
|
||||
### 6. Webhooks (Optional)
|
||||
|
||||
[Description of webhook system if applicable]
|
||||
|
||||
**Webhook Events**:
|
||||
- `resource.created` - Triggered when a new resource is created
|
||||
- `resource.updated` - Triggered when a resource is updated
|
||||
- `resource.deleted` - Triggered when a resource is deleted
|
||||
|
||||
**Webhook Payload Example**:
|
||||
```json
|
||||
{
|
||||
"event": "resource.created",
|
||||
"timestamp": "2024-01-20T12:00:00Z",
|
||||
"data": {
|
||||
"id": 124,
|
||||
"field1": "value"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Include only relevant sections** - Skip Part A for pure web services, skip Part B for pure libraries
|
||||
2. **Signatures only in Part A** - No implementation code in Code API section
|
||||
3. **Complete examples in Part B** - All HTTP examples should be runnable
|
||||
4. **Consistent formatting** - Use language-specific code blocks (TypeScript, HTTP, JSON, bash)
|
||||
5. **Brief descriptions** - One line per item is sufficient for Code API
|
||||
6. **Detailed explanations for HTTP** - Include request/response examples, validation rules, error cases
|
||||
7. **Alphabetical order** - Sort items within each section for easy lookup
|
||||
8. **Public API only** - Do not document internal/private exports or endpoints
|
||||
|
||||
---
|
||||
|
||||
## Template Usage Guidelines
|
||||
|
||||
### For Module-Level API.md (Code API)
|
||||
**Use**: Part A only
|
||||
**Location**: `modules/[module-name]/API.md`
|
||||
**Focus**: Exported functions, classes, interfaces
|
||||
|
||||
### For Project-Level HTTP API Documentation
|
||||
**Use**: Part B only
|
||||
**Location**: `.workflow/docs/api/README.md`
|
||||
**Focus**: REST/GraphQL endpoints, authentication
|
||||
|
||||
### For Full-Stack Projects (Both Code and HTTP APIs)
|
||||
**Use**: Both Part A and Part B
|
||||
**Organization**:
|
||||
- Part A for SDK/client library APIs
|
||||
- Part B for HTTP endpoints
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**API Version**: [Version number]
|
||||
**Module/Service Path**: [Auto-fill with actual path]
|
||||
...(content truncated)...
|
||||
@@ -1,68 +1,27 @@
|
||||
# Folder Navigation Documentation Template
|
||||
Generate a navigation README for directories that contain only subdirectories.
|
||||
|
||||
Generate a navigation README for directories that contain only subdirectories (no code files). This serves as an index to help readers navigate to specific modules.
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Keep the content brief and act as an index
|
||||
□ Use one-line descriptions for each module
|
||||
□ Ensure all mentioned modules link to their respective READMEs
|
||||
□ Use scannable formats like tables and lists
|
||||
|
||||
## Structure
|
||||
## REQUIRED CONTENT
|
||||
1. **Overview**: Brief description of the directory's purpose.
|
||||
2. **Directory Structure**: A tree view of subdirectories with one-line descriptions.
|
||||
3. **Module Quick Reference**: A table with links, purposes, and key features.
|
||||
4. **How to Navigate**: Guidance on which module to explore for specific needs.
|
||||
5. **Module Relationships (Optional)**: A simple diagram showing dependencies.
|
||||
|
||||
### 1. Overview
|
||||
## OUTPUT REQUIREMENTS
|
||||
- A scannable index for navigating subdirectories.
|
||||
- Links to each submodule's detailed documentation.
|
||||
- A clear, high-level overview of the directory's contents.
|
||||
|
||||
Brief description of what this directory/category contains:
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ The generated README is brief and serves as a scannable index
|
||||
□ All submodules are linked correctly
|
||||
□ Descriptions are concise and clear
|
||||
□ The structure follows the required content outline
|
||||
|
||||
> The `modules/` directory contains the core business logic modules of the application. Each subdirectory represents a self-contained functional module with its own responsibilities.
|
||||
|
||||
### 2. Directory Structure
|
||||
|
||||
Provide a tree view of the subdirectories with brief descriptions:
|
||||
|
||||
```
|
||||
modules/
|
||||
├── auth/ - User authentication and authorization
|
||||
├── api/ - API route handlers and middleware
|
||||
├── database/ - Database connections and ORM models
|
||||
└── utils/ - Shared utility functions
|
||||
```
|
||||
|
||||
### 3. Module Quick Reference
|
||||
|
||||
Table format for quick scanning:
|
||||
|
||||
| Module | Purpose | Key Features |
|
||||
|--------|---------|--------------|
|
||||
| [auth](./auth/) | Authentication | JWT tokens, session management |
|
||||
| [api](./api/) | API routing | REST endpoints, validation |
|
||||
| [database](./database/) | Data layer | PostgreSQL, migrations |
|
||||
| [utils](./utils/) | Utilities | Logging, helpers |
|
||||
|
||||
### 4. How to Navigate
|
||||
|
||||
Guidance on which module to explore based on needs:
|
||||
|
||||
- **For authentication logic** → [auth module](./auth/)
|
||||
- **For API endpoints** → [api module](./api/)
|
||||
- **For database queries** → [database module](./database/)
|
||||
- **For helper functions** → [utils module](./utils/)
|
||||
|
||||
### 5. Module Relationships (Optional)
|
||||
|
||||
If modules have significant dependencies, show them:
|
||||
|
||||
```
|
||||
api → auth (uses for authentication)
|
||||
api → database (uses for data access)
|
||||
auth → database (uses for user storage)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Keep it brief** - This is an index, not detailed documentation
|
||||
2. **One-line descriptions** - Each module gets a concise purpose statement
|
||||
3. **Scannable format** - Use tables and lists for quick navigation
|
||||
4. **Link to submodules** - Every module mentioned should link to its README
|
||||
5. **No code examples** - This is navigation only
|
||||
|
||||
---
|
||||
|
||||
**Directory Path**: [Auto-fill with actual directory path]
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
Focus: Creating a clear and concise navigation hub for parent directories.
|
||||
@@ -1,98 +1,40 @@
|
||||
# Module README Documentation Template
|
||||
Generate comprehensive module documentation focused on understanding and usage.
|
||||
|
||||
Generate comprehensive module documentation focused on understanding and usage. Explain WHAT the module does, WHY it exists, and HOW to use it. Do NOT duplicate API signatures (those belong in API.md).
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Explain WHAT the module does, WHY it exists, and HOW to use it
|
||||
□ Do NOT duplicate API signatures from API.md; refer to it instead
|
||||
□ Provide practical, real-world usage examples
|
||||
□ Clearly define the module's boundaries and dependencies
|
||||
|
||||
## Structure
|
||||
## DOCUMENTATION STRUCTURE
|
||||
|
||||
### 1. Purpose
|
||||
|
||||
**What**: Clearly state what this module is responsible for
|
||||
**Why**: Explain why this module exists and what problems it solves
|
||||
**Boundaries**: Define what is IN scope and OUT of scope
|
||||
|
||||
Example:
|
||||
> The `auth` module handles user authentication and authorization. It exists to centralize security logic and provide a consistent authentication interface across the application. It does NOT handle user profile management or session storage.
|
||||
- **What**: Clearly state what this module is responsible for.
|
||||
- **Why**: Explain the problem it solves.
|
||||
- **Boundaries**: Define what is in and out of scope.
|
||||
|
||||
### 2. Core Concepts
|
||||
|
||||
List and explain key concepts, patterns, or abstractions used by this module:
|
||||
|
||||
- **Concept 1**: [Brief explanation of important concept]
|
||||
- **Concept 2**: [Another key concept users should understand]
|
||||
- **Pattern**: [Architectural pattern used, e.g., "Uses middleware pattern for request processing"]
|
||||
- Explain key concepts, patterns, or abstractions.
|
||||
|
||||
### 3. Usage Scenarios
|
||||
|
||||
Provide 2-4 common use cases with code examples:
|
||||
|
||||
#### Scenario 1: [Common use case title]
|
||||
```typescript
|
||||
// Brief example showing how to use the module for this scenario
|
||||
import { functionName } from './module';
|
||||
|
||||
const result = functionName(input);
|
||||
```
|
||||
|
||||
#### Scenario 2: [Another common use case]
|
||||
```typescript
|
||||
// Another practical example
|
||||
```
|
||||
- Provide 2-4 common use cases with code examples.
|
||||
|
||||
### 4. Dependencies
|
||||
|
||||
#### Internal Dependencies
|
||||
List other project modules this module depends on and explain why:
|
||||
- **[Module Name]** - [Why this dependency exists and what it provides]
|
||||
|
||||
#### External Dependencies
|
||||
List third-party libraries and their purpose:
|
||||
- **[Library Name]** (`version`) - [What functionality it provides to this module]
|
||||
- List internal and external dependencies with explanations.
|
||||
|
||||
### 5. Configuration
|
||||
|
||||
#### Environment Variables
|
||||
List any environment variables the module uses:
|
||||
- `ENV_VAR_NAME` - [Description, type, default value]
|
||||
|
||||
#### Configuration Options
|
||||
If the module accepts configuration objects:
|
||||
```typescript
|
||||
// Example configuration
|
||||
const config = {
|
||||
option1: value, // Description of option1
|
||||
option2: value, // Description of option2
|
||||
};
|
||||
```
|
||||
- Document environment variables and configuration options.
|
||||
|
||||
### 6. Testing
|
||||
|
||||
Explain how to test code that uses this module:
|
||||
```bash
|
||||
# Command to run tests for this module
|
||||
npm test -- path/to/module
|
||||
```
|
||||
|
||||
**Test Coverage**: [Brief note on what's tested]
|
||||
- Explain how to run tests for the module.
|
||||
|
||||
### 7. Common Issues
|
||||
- List common problems and their solutions.
|
||||
|
||||
List 2-3 common problems and their solutions:
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ The module's purpose, scope, and boundaries are clearly defined
|
||||
□ Core concepts are explained for better understanding
|
||||
□ Usage examples are practical and demonstrate real-world scenarios
|
||||
□ All dependencies and configuration options are documented
|
||||
|
||||
#### Issue: [Common problem description]
|
||||
**Solution**: [How to resolve it]
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **No API duplication** - Refer to API.md for signatures
|
||||
2. **Focus on understanding** - Explain concepts, not just code
|
||||
3. **Practical examples** - Show real usage, not trivial cases
|
||||
4. **Clear dependencies** - Help readers understand module relationships
|
||||
5. **Concise** - Each section should be scannable and to-the-point
|
||||
|
||||
---
|
||||
|
||||
**Module Path**: [Auto-fill with actual module path]
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**See also**: [Link to API.md for interface details]
|
||||
Focus: Explaining the module's purpose and usage, not just its API.
|
||||
@@ -1,167 +1,41 @@
|
||||
# Project Architecture Documentation Template
|
||||
Generate comprehensive architecture documentation for the entire project.
|
||||
|
||||
Generate comprehensive architecture documentation that synthesizes information from all module documents. Focus on system-level design, module relationships, and aggregated API overview. This document should be created AFTER all module documentation is complete.
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Synthesize information from all modules; do not duplicate content
|
||||
□ Maintain a system-level perspective, focusing on module interactions
|
||||
□ Use visual aids (like ASCII diagrams) to clarify structure
|
||||
□ Explain the WHY behind architectural decisions
|
||||
|
||||
## Structure
|
||||
## DOCUMENTATION STRUCTURE
|
||||
|
||||
### 1. System Overview
|
||||
|
||||
High-level description of the system architecture:
|
||||
|
||||
**Architectural Style**: [e.g., Layered, Microservices, Event-Driven, Hexagonal]
|
||||
|
||||
**Core Principles**:
|
||||
- [Principle 1, e.g., "Separation of concerns"]
|
||||
- [Principle 2, e.g., "Dependency inversion"]
|
||||
- [Principle 3, e.g., "Single responsibility"]
|
||||
|
||||
**Technology Stack**:
|
||||
- **Languages**: [Primary programming languages]
|
||||
- **Frameworks**: [Key frameworks]
|
||||
- **Databases**: [Data storage solutions]
|
||||
- **Infrastructure**: [Deployment, hosting, CI/CD]
|
||||
- Architectural Style, Core Principles, and Technology Stack.
|
||||
|
||||
### 2. System Structure
|
||||
|
||||
Visual representation of the system structure using text diagrams:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Application Layer │
|
||||
│ (API Routes, Controllers) │
|
||||
└────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────┐
|
||||
│ Business Logic Layer │
|
||||
│ (Modules: auth, orders, payments) │
|
||||
└────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────┐
|
||||
│ Data Access Layer │
|
||||
│ (Database, ORM, Repositories) │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
- Visual representation of the system's layers or components.
|
||||
|
||||
### 3. Module Map
|
||||
|
||||
Comprehensive list of all modules with their responsibilities:
|
||||
|
||||
| Module | Layer | Responsibility | Dependencies |
|
||||
|--------|-------|----------------|--------------|
|
||||
| `auth` | Business | Authentication & authorization | database, utils |
|
||||
| `api` | Application | HTTP routing & validation | auth, orders |
|
||||
| `database` | Data | Data persistence | - |
|
||||
| `utils` | Infrastructure | Shared utilities | - |
|
||||
- A table listing all modules, their layers, responsibilities, and dependencies.
|
||||
|
||||
### 4. Module Interactions
|
||||
|
||||
Describe key interaction patterns between modules:
|
||||
|
||||
#### Data Flow Example: User Authentication
|
||||
```
|
||||
1. Client → api/login endpoint
|
||||
2. api → auth.authenticateUser()
|
||||
3. auth → database.findUser()
|
||||
4. database → PostgreSQL
|
||||
5. auth → JWT token generation
|
||||
6. api → Response with token
|
||||
```
|
||||
|
||||
#### Dependency Graph
|
||||
```
|
||||
api ──────┐
|
||||
├──→ auth ───→ database
|
||||
orders ───┤ ↑
|
||||
└──────────────┘
|
||||
```
|
||||
- Describe key data flows and show a dependency graph.
|
||||
|
||||
### 5. Design Patterns
|
||||
|
||||
Document key architectural patterns used:
|
||||
|
||||
#### Pattern 1: [Pattern Name, e.g., "Repository Pattern"]
|
||||
- **Where**: [Which modules use this pattern]
|
||||
- **Why**: [Reason for using this pattern]
|
||||
- **How**: [Brief explanation of implementation]
|
||||
|
||||
#### Pattern 2: [Another pattern]
|
||||
[Similar structure]
|
||||
- Document key architectural patterns used across the project.
|
||||
|
||||
### 6. Aggregated API Overview
|
||||
|
||||
High-level summary of all public APIs across modules. Group by category:
|
||||
|
||||
#### Authentication APIs
|
||||
- `auth.authenticate(credentials)` - Validate user credentials
|
||||
- `auth.authorize(user, permission)` - Check user permissions
|
||||
- `auth.generateToken(userId)` - Create JWT token
|
||||
|
||||
#### Data APIs
|
||||
- `database.findOne(query)` - Find single record
|
||||
- `database.findMany(query)` - Find multiple records
|
||||
- `database.insert(data)` - Insert new record
|
||||
|
||||
#### Utility APIs
|
||||
- `utils.logger.log(message)` - Application logging
|
||||
- `utils.validator.validate(data, schema)` - Data validation
|
||||
|
||||
*Note: For detailed API signatures, refer to individual module API.md files*
|
||||
- A high-level summary of all public APIs, grouped by category.
|
||||
|
||||
### 7. Data Flow
|
||||
- Describe the typical request lifecycle or event flow.
|
||||
|
||||
Describe how data moves through the system:
|
||||
### 8. Security and Scalability
|
||||
- Overview of security measures and scalability considerations.
|
||||
|
||||
**Request Lifecycle**:
|
||||
1. HTTP request enters through API layer
|
||||
2. Request validation and authentication (auth module)
|
||||
3. Business logic processing (domain modules)
|
||||
4. Data persistence (database module)
|
||||
5. Response formatting and return
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ The documentation provides a cohesive, system-level view
|
||||
□ Module interactions and dependencies are clearly illustrated
|
||||
□ The rationale behind major design patterns and decisions is explained
|
||||
□ The document synthesizes, rather than duplicates, module-level details
|
||||
|
||||
**Event Flow** (if applicable):
|
||||
- [Describe event-driven flows if present]
|
||||
|
||||
### 8. Security Architecture
|
||||
|
||||
Overview of security measures:
|
||||
|
||||
- **Authentication**: [JWT, OAuth2, etc.]
|
||||
- **Authorization**: [RBAC, ACL, etc.]
|
||||
- **Data Protection**: [Encryption, hashing]
|
||||
- **API Security**: [Rate limiting, CORS, etc.]
|
||||
|
||||
### 9. Scalability Considerations
|
||||
|
||||
Architectural decisions that support scalability:
|
||||
|
||||
- [Horizontal scaling approach]
|
||||
- [Caching strategy]
|
||||
- [Database optimization]
|
||||
- [Load balancing]
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Synthesize, don't duplicate** - Reference module docs, don't copy them
|
||||
2. **System-level perspective** - Focus on how modules work together
|
||||
3. **Visual aids** - Use diagrams for clarity (ASCII art is fine)
|
||||
4. **Aggregated APIs** - One-line summaries only, link to detailed docs
|
||||
5. **Design rationale** - Explain WHY decisions were made
|
||||
6. **Maintain consistency** - Ensure all module docs are considered
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
This document requires the following to be available:
|
||||
- All module README.md files (for understanding module purposes)
|
||||
- All module API.md files (for aggregating API overview)
|
||||
- Project README.md (for context and navigation)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**See also**:
|
||||
- [Project README](./README.md) for project overview
|
||||
- [Module Documentation](./modules/) for detailed module docs
|
||||
Focus: Providing a holistic, system-level understanding of the project architecture.
|
||||
@@ -1,205 +1,35 @@
|
||||
# Project Examples Documentation Template
|
||||
Generate practical, end-to-end examples demonstrating core project usage.
|
||||
|
||||
Generate practical, end-to-end examples demonstrating core usage patterns of the project. Focus on realistic scenarios that span multiple modules. These examples should help users understand how to accomplish common tasks.
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Provide complete, runnable code for every example
|
||||
□ Focus on realistic, real-world scenarios, not trivial cases
|
||||
□ Explain the flow and how different modules interact
|
||||
□ Include expected output to verify correctness
|
||||
|
||||
## Structure
|
||||
## EXAMPLES STRUCTURE
|
||||
|
||||
### 1. Introduction
|
||||
|
||||
Brief overview of what these examples cover:
|
||||
|
||||
> This document provides complete, working examples for common use cases. Each example demonstrates how multiple modules work together to accomplish a specific task.
|
||||
|
||||
**Prerequisites**:
|
||||
- [List required setup, e.g., "Project installed and configured"]
|
||||
- [Environment requirements, e.g., "PostgreSQL running on localhost"]
|
||||
- Overview of the examples and any prerequisites.
|
||||
|
||||
### 2. Quick Start Example
|
||||
|
||||
The simplest possible working example to get started:
|
||||
|
||||
```typescript
|
||||
// The minimal example to verify setup
|
||||
import { App } from './src';
|
||||
|
||||
const app = new App();
|
||||
await app.start();
|
||||
console.log('Application running!');
|
||||
```
|
||||
|
||||
**What this does**: [Brief explanation]
|
||||
- The simplest possible working example to verify setup.
|
||||
|
||||
### 3. Core Use Cases
|
||||
- 3-5 complete examples for common scenarios with code, output, and explanations.
|
||||
|
||||
Provide 3-5 complete examples for common scenarios:
|
||||
### 4. Advanced & Integration Examples
|
||||
- Showcase more complex scenarios or integrations with external systems.
|
||||
|
||||
#### Example 1: [Scenario Name, e.g., "User Registration and Login"]
|
||||
### 5. Testing Examples
|
||||
- Show how to test code that uses the project.
|
||||
|
||||
**Objective**: [What this example accomplishes]
|
||||
### 6. Best Practices & Troubleshooting
|
||||
- Demonstrate recommended patterns and provide solutions to common issues.
|
||||
|
||||
**Modules involved**: `auth`, `database`, `api`
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ All examples are complete, runnable, and tested
|
||||
□ Scenarios are realistic and demonstrate key project features
|
||||
□ Explanations clarify module interactions and data flow
|
||||
□ Best practices and error handling are demonstrated
|
||||
|
||||
**Complete code**:
|
||||
```typescript
|
||||
import { createUser, authenticateUser } from './modules/auth';
|
||||
import { startServer } from './modules/api';
|
||||
|
||||
// Step 1: Initialize the application
|
||||
const app = await startServer({ port: 3000 });
|
||||
|
||||
// Step 2: Register a new user
|
||||
const user = await createUser({
|
||||
email: 'user@example.com',
|
||||
password: 'securePassword123',
|
||||
name: 'John Doe'
|
||||
});
|
||||
|
||||
// Step 3: Authenticate the user
|
||||
const session = await authenticateUser({
|
||||
email: 'user@example.com',
|
||||
password: 'securePassword123'
|
||||
});
|
||||
|
||||
// Step 4: Use the authentication token
|
||||
console.log('Login successful, token:', session.token);
|
||||
```
|
||||
|
||||
**Expected output**:
|
||||
```
|
||||
Server started on port 3000
|
||||
User created: { id: 1, email: 'user@example.com', name: 'John Doe' }
|
||||
Login successful, token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
**Explanation**:
|
||||
1. [Step-by-step breakdown of what each part does]
|
||||
2. [How modules interact]
|
||||
3. [Common variations or customizations]
|
||||
|
||||
---
|
||||
|
||||
#### Example 2: [Another Common Scenario]
|
||||
|
||||
[Similar structure with complete code]
|
||||
|
||||
---
|
||||
|
||||
#### Example 3: [Another Use Case]
|
||||
|
||||
[Similar structure with complete code]
|
||||
|
||||
### 4. Advanced Examples
|
||||
|
||||
More complex scenarios for power users:
|
||||
|
||||
#### Advanced Example 1: [Complex Scenario]
|
||||
|
||||
**Objective**: [What this example accomplishes]
|
||||
|
||||
**Modules involved**: [List]
|
||||
|
||||
```typescript
|
||||
// Complete working code with detailed comments
|
||||
```
|
||||
|
||||
**Key points**:
|
||||
- [Important concept or gotcha]
|
||||
- [Performance consideration]
|
||||
- [Security note]
|
||||
|
||||
### 5. Integration Examples
|
||||
|
||||
Examples showing how to integrate with external systems:
|
||||
|
||||
#### Integration with [External System]
|
||||
|
||||
```typescript
|
||||
// Example of integrating with a third-party service
|
||||
```
|
||||
|
||||
### 6. Testing Examples
|
||||
|
||||
Show how to test code that uses this project:
|
||||
|
||||
```typescript
|
||||
// Example test case using the project
|
||||
import { describe, it, expect } from 'your-test-framework';
|
||||
|
||||
describe('User authentication', () => {
|
||||
it('should authenticate valid credentials', async () => {
|
||||
const result = await authenticateUser({
|
||||
email: 'test@example.com',
|
||||
password: 'password123'
|
||||
});
|
||||
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.token).toBeDefined();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 7. Best Practices
|
||||
|
||||
Demonstrate recommended patterns:
|
||||
|
||||
#### Pattern 1: [Best Practice Title]
|
||||
```typescript
|
||||
// Good: Recommended approach
|
||||
const result = await handleWithErrorRecovery(operation);
|
||||
|
||||
// Bad: Anti-pattern to avoid
|
||||
const result = operation(); // No error handling
|
||||
```
|
||||
|
||||
**Why**: [Explanation of why this is the best approach]
|
||||
|
||||
#### Pattern 2: [Another Best Practice]
|
||||
[Similar structure]
|
||||
|
||||
### 8. Troubleshooting Common Issues
|
||||
|
||||
Example-based solutions to common problems:
|
||||
|
||||
#### Issue: [Common Problem]
|
||||
|
||||
**Symptom**: [What the user experiences]
|
||||
|
||||
**Solution**:
|
||||
```typescript
|
||||
// Before: Code that causes the issue
|
||||
const broken = doSomethingWrong();
|
||||
|
||||
// After: Corrected code
|
||||
const fixed = doSomethingRight();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Complete, runnable code** - Every example should be copy-paste ready
|
||||
2. **Real-world scenarios** - Avoid trivial or contrived examples
|
||||
3. **Explain the flow** - Show how modules work together
|
||||
4. **Include output** - Show what users should expect to see
|
||||
5. **Error handling** - Demonstrate proper error handling patterns
|
||||
6. **Comment complex parts** - Help readers understand non-obvious code
|
||||
7. **Version compatibility** - Note if examples are version-specific
|
||||
|
||||
---
|
||||
|
||||
## Code Quality Standards
|
||||
|
||||
All example code should:
|
||||
- Follow project coding standards
|
||||
- Include proper error handling
|
||||
- Use async/await correctly
|
||||
- Show TypeScript types where applicable
|
||||
- Be tested and verified to work
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**See also**:
|
||||
- [Project README](./README.md) for getting started
|
||||
- [Architecture](./ARCHITECTURE.md) for understanding system design
|
||||
- [Module Documentation](./modules/) for API details
|
||||
Focus: Helping users accomplish common tasks through complete, practical examples.
|
||||
@@ -1,58 +1,35 @@
|
||||
# Project-Level Documentation Template
|
||||
Generate a comprehensive project-level README documentation.
|
||||
|
||||
Generate comprehensive project documentation following this structure:
|
||||
## CORE CHECKLIST ⚡
|
||||
□ Clearly state the project's purpose and target audience
|
||||
□ Provide clear, runnable instructions for getting started
|
||||
□ Outline the development workflow and coding standards
|
||||
□ Offer a high-level overview of the project structure and architecture
|
||||
|
||||
## 1. Overview
|
||||
- **Purpose**: [High-level mission and goals of the project]
|
||||
- **Target Audience**: [Primary users, developers, stakeholders]
|
||||
- **Key Features**: [List of major functionalities and capabilities]
|
||||
## README STRUCTURE
|
||||
|
||||
## 2. System Architecture
|
||||
- **Architectural Style**: [e.g., Monolith, Microservices, Layered, Event-Driven]
|
||||
- **Core Components**: [Diagram or list of major system parts and their interactions]
|
||||
- **Technology Stack**:
|
||||
- Languages: [Programming languages used]
|
||||
- Frameworks: [Key frameworks and libraries]
|
||||
- Databases: [Data storage solutions]
|
||||
- Infrastructure: [Deployment and hosting]
|
||||
- **Design Principles**: [Guiding principles like SOLID, DRY, separation of concerns]
|
||||
### 1. Overview
|
||||
- Purpose, Target Audience, and Key Features.
|
||||
|
||||
## 3. Getting Started
|
||||
- **Prerequisites**: [Required software, tools, versions]
|
||||
- **Installation**:
|
||||
```bash
|
||||
# Installation commands
|
||||
```
|
||||
- **Configuration**: [Environment setup, config files]
|
||||
- **Running the Project**:
|
||||
```bash
|
||||
# Startup commands
|
||||
```
|
||||
### 2. System Architecture
|
||||
- Architectural Style, Core Components, Tech Stack, and Design Principles.
|
||||
|
||||
## 4. Development Workflow
|
||||
- **Branching Strategy**: [e.g., GitFlow, trunk-based]
|
||||
- **Coding Standards**: [Style guide, linting rules]
|
||||
- **Testing**:
|
||||
```bash
|
||||
# Test commands
|
||||
```
|
||||
- **Build & Deployment**: [CI/CD pipeline overview]
|
||||
### 3. Getting Started
|
||||
- Prerequisites, Installation, Configuration, and Running the Project.
|
||||
|
||||
## 5. Project Structure
|
||||
```
|
||||
project-root/
|
||||
├── src/ # [Description]
|
||||
├── tests/ # [Description]
|
||||
├── docs/ # [Description]
|
||||
└── config/ # [Description]
|
||||
```
|
||||
### 4. Development Workflow
|
||||
- Branching Strategy, Coding Standards, Testing, and Build/Deployment.
|
||||
|
||||
## 6. Navigation
|
||||
- [Module Documentation](./modules/)
|
||||
- [API Reference](./api/)
|
||||
- [Architecture Details](./architecture/)
|
||||
- [Contributing Guidelines](./CONTRIBUTING.md)
|
||||
### 5. Project Structure
|
||||
- A high-level tree view of the main directories.
|
||||
|
||||
---
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**Documentation Version**: [Project version]
|
||||
### 6. Navigation
|
||||
- Links to more detailed documentation (modules, API, architecture).
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ The project's purpose and value proposition are clear
|
||||
□ A new developer can successfully set up and run the project
|
||||
□ The development process and standards are well-defined
|
||||
□ The README provides clear navigation to other key documents
|
||||
|
||||
Focus: Providing a central entry point for new users and developers to understand and run the project.
|
||||
Reference in New Issue
Block a user