mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
Refactor documentation workflow and templates
- Updated `/workflow:docs` command to enhance documentation planning and orchestration. - Introduced new parameters for tool selection and scope filtering. - Separated documentation planning from content generation, clarifying roles of docs.md and doc-generator.md. - Added detailed planning process phases, including session initialization, project structure analysis, and task decomposition. - Created new templates for API, module, and project-level documentation, ensuring comprehensive coverage and consistency. - Enhanced output structure for better organization of generated documentation. - Implemented error handling and completion checklist for improved user experience.
This commit is contained in:
catlog22
@@ -0,0 +1,240 @@
|
||||
# API-Level Documentation Template
|
||||
|
||||
Generate comprehensive API documentation following this structure:
|
||||
|
||||
## Overview
|
||||
[Brief description of the API's purpose and capabilities]
|
||||
|
||||
## Authentication
|
||||
### Authentication Method
|
||||
[e.g., JWT, OAuth2, API Keys]
|
||||
|
||||
### Obtaining Credentials
|
||||
```bash
|
||||
# Example authentication flow
|
||||
```
|
||||
|
||||
### Using Credentials
|
||||
```http
|
||||
GET /api/resource HTTP/1.1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Base URL
|
||||
```
|
||||
Production: https://api.example.com/v1
|
||||
Staging: https://staging.api.example.com/v1
|
||||
```
|
||||
|
||||
## Common Response Codes
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 200 | Success |
|
||||
| 201 | Created |
|
||||
| 400 | Bad Request |
|
||||
| 401 | Unauthorized |
|
||||
| 403 | Forbidden |
|
||||
| 404 | Not Found |
|
||||
| 500 | Internal Server Error |
|
||||
|
||||
---
|
||||
|
||||
## Endpoints
|
||||
|
||||
### Resource: Users
|
||||
|
||||
#### GET /users
|
||||
**Description**: Retrieves a paginated list of users.
|
||||
|
||||
**Query Parameters**:
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `limit` | number | No | Number of results (default: 20, max: 100) |
|
||||
| `offset` | number | No | Pagination offset (default: 0) |
|
||||
| `sort` | string | No | Sort field (e.g., `name`, `-created_at`) |
|
||||
|
||||
**Example Request**:
|
||||
```http
|
||||
GET /users?limit=10&offset=0&sort=-created_at HTTP/1.1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Response (200 OK)**:
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "John Doe",
|
||||
"email": "john@example.com",
|
||||
"created_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"total": 100,
|
||||
"limit": 10,
|
||||
"offset": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Error Response (401 Unauthorized)**:
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "UNAUTHORIZED",
|
||||
"message": "Invalid or expired token"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### GET /users/:id
|
||||
**Description**: Retrieves a single user by ID.
|
||||
|
||||
**Path Parameters**:
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `id` | number | User ID |
|
||||
|
||||
**Example Request**:
|
||||
```http
|
||||
GET /users/123 HTTP/1.1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Response (200 OK)**:
|
||||
```json
|
||||
{
|
||||
"id": 123,
|
||||
"name": "John Doe",
|
||||
"email": "john@example.com",
|
||||
"created_at": "2024-01-01T00:00:00Z",
|
||||
"updated_at": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### POST /users
|
||||
**Description**: Creates a new user.
|
||||
|
||||
**Request Body**:
|
||||
```json
|
||||
{
|
||||
"name": "Jane Smith",
|
||||
"email": "jane@example.com",
|
||||
"password": "securePassword123"
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Rules**:
|
||||
- `name`: Required, 2-100 characters
|
||||
- `email`: Required, valid email format, must be unique
|
||||
- `password`: Required, minimum 8 characters
|
||||
|
||||
**Response (201 Created)**:
|
||||
```json
|
||||
{
|
||||
"id": 124,
|
||||
"name": "Jane Smith",
|
||||
"email": "jane@example.com",
|
||||
"created_at": "2024-01-20T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Error Response (400 Bad Request)**:
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "Validation failed",
|
||||
"details": [
|
||||
{
|
||||
"field": "email",
|
||||
"message": "Email already exists"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### PUT /users/:id
|
||||
**Description**: Updates an existing user.
|
||||
|
||||
**Path Parameters**:
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `id` | number | User ID |
|
||||
|
||||
**Request Body** (all fields optional):
|
||||
```json
|
||||
{
|
||||
"name": "Jane Doe",
|
||||
"email": "jane.doe@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
**Response (200 OK)**:
|
||||
```json
|
||||
{
|
||||
"id": 124,
|
||||
"name": "Jane Doe",
|
||||
"email": "jane.doe@example.com",
|
||||
"updated_at": "2024-01-21T09:15:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### DELETE /users/:id
|
||||
**Description**: Deletes a user.
|
||||
|
||||
**Path Parameters**:
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `id` | number | User ID |
|
||||
|
||||
**Response (204 No Content)**:
|
||||
[Empty response body]
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
## SDKs and Client Libraries
|
||||
- [JavaScript/TypeScript SDK](./sdks/javascript.md)
|
||||
- [Python SDK](./sdks/python.md)
|
||||
|
||||
---
|
||||
|
||||
## Webhooks
|
||||
[Description of webhook system if applicable]
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
### v1.1.0 (2024-01-20)
|
||||
- Added user sorting functionality
|
||||
- Improved error messages
|
||||
|
||||
### v1.0.0 (2024-01-01)
|
||||
- Initial API release
|
||||
|
||||
---
|
||||
|
||||
**API Version**: 1.1.0
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**Support**: api-support@example.com
|
||||
@@ -0,0 +1,91 @@
|
||||
# Module-Level Documentation Template
|
||||
|
||||
Generate detailed module documentation following this structure:
|
||||
|
||||
## 1. Purpose and Responsibilities
|
||||
[What this module does, its boundaries, and its role in the larger system]
|
||||
|
||||
## 2. Internal Architecture
|
||||
- **Key Components**:
|
||||
- [Component 1]: [Description and responsibility]
|
||||
- [Component 2]: [Description and responsibility]
|
||||
- **Data Flow**: [How data moves through the module, with diagrams if applicable]
|
||||
- **Core Logic**: [Explanation of the main business logic and algorithms]
|
||||
- **State Management**: [How state is managed within the module]
|
||||
|
||||
## 3. Public API / Interface
|
||||
### Exported Functions
|
||||
```typescript
|
||||
/**
|
||||
* Function description
|
||||
* @param param1 - Parameter description
|
||||
* @returns Return value description
|
||||
*/
|
||||
export function exampleFunction(param1: Type): ReturnType;
|
||||
```
|
||||
|
||||
### Exported Classes
|
||||
```typescript
|
||||
/**
|
||||
* Class description
|
||||
*/
|
||||
export class ExampleClass {
|
||||
// Public methods and properties
|
||||
}
|
||||
```
|
||||
|
||||
### Usage Examples
|
||||
```typescript
|
||||
import { exampleFunction } from './module';
|
||||
|
||||
// Example 1: Basic usage
|
||||
const result = exampleFunction(input);
|
||||
|
||||
// Example 2: Advanced usage
|
||||
// ...
|
||||
```
|
||||
|
||||
## 4. Dependencies
|
||||
### Internal Dependencies
|
||||
- **[Module A]**: [Why this dependency exists, what it provides]
|
||||
- **[Module B]**: [Purpose of dependency]
|
||||
|
||||
### External Dependencies
|
||||
- **[Library 1]** (`version`): [Purpose and usage]
|
||||
- **[Library 2]** (`version`): [Purpose and usage]
|
||||
|
||||
## 5. Configuration
|
||||
### Environment Variables
|
||||
- `ENV_VAR_NAME`: [Description, default value]
|
||||
|
||||
### Configuration Options
|
||||
```typescript
|
||||
interface ModuleConfig {
|
||||
option1: Type; // Description
|
||||
option2: Type; // Description
|
||||
}
|
||||
```
|
||||
|
||||
## 6. Testing
|
||||
### Running Tests
|
||||
```bash
|
||||
npm test -- module-name
|
||||
```
|
||||
|
||||
### Test Coverage
|
||||
- Unit tests: [Coverage percentage or key test files]
|
||||
- Integration tests: [Coverage or test scenarios]
|
||||
|
||||
## 7. Common Use Cases
|
||||
1. **Use Case 1**: [Description and code example]
|
||||
2. **Use Case 2**: [Description and code example]
|
||||
|
||||
## 8. Troubleshooting
|
||||
### Common Issues
|
||||
- **Issue 1**: [Description and solution]
|
||||
- **Issue 2**: [Description and solution]
|
||||
|
||||
---
|
||||
**Module Path**: [File path]
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**Owner/Maintainer**: [Team or individual]
|
||||
@@ -0,0 +1,58 @@
|
||||
# Project-Level Documentation Template
|
||||
|
||||
Generate comprehensive project documentation following this structure:
|
||||
|
||||
## 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]
|
||||
|
||||
## 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]
|
||||
|
||||
## 3. Getting Started
|
||||
- **Prerequisites**: [Required software, tools, versions]
|
||||
- **Installation**:
|
||||
```bash
|
||||
# Installation commands
|
||||
```
|
||||
- **Configuration**: [Environment setup, config files]
|
||||
- **Running the Project**:
|
||||
```bash
|
||||
# Startup commands
|
||||
```
|
||||
|
||||
## 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]
|
||||
|
||||
## 5. Project Structure
|
||||
```
|
||||
project-root/
|
||||
├── src/ # [Description]
|
||||
├── tests/ # [Description]
|
||||
├── docs/ # [Description]
|
||||
└── config/ # [Description]
|
||||
```
|
||||
|
||||
## 6. Navigation
|
||||
- [Module Documentation](./modules/)
|
||||
- [API Reference](./api/)
|
||||
- [Architecture Details](./architecture/)
|
||||
- [Contributing Guidelines](./CONTRIBUTING.md)
|
||||
|
||||
---
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**Documentation Version**: [Project version]
|
||||
Reference in New Issue
Block a user