tasks-documentation（任务文档）

[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ask user whether to skip.

Prerequisites: MUST READ .claude/skills/shared/evidence-based-reasoning-protocol.md before executing.

Quick Summary

Goal: Autonomous documentation generation with structured templates for code comments, API docs, and architecture docs (subagent variant of documentation).

Workflow:

1. Identify Type — Code comments, API documentation, or architecture documentation
2. Apply Pattern — C# XML docs, TypeScript JSDoc, API endpoint docs, README structure, or inline comments
3. Follow Guidelines — Document "why" not "what", include examples, keep close to code, update with changes

Key Rules:

• Autonomous: Use for documentation tasks without user feedback loop
• DO: Document public APIs, explain "why", include usage examples, keep docs close to code
• DON'T: State obvious, leave TODOs indefinitely, duplicate code in docs, create separate stale docs
• Comment Types: <summary> for public APIs, // for complex logic, TODO/FIXME/HACK/NOTE markers

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof.

Skill Variant: Use this skill for autonomous documentation generation with structured templates. For interactive documentation tasks with user feedback, use documentation instead.

Documentation Workflow

When to Use This Skill

• Creating API documentation
• Writing code comments
• Updating README files
• Generating architecture documentation

Documentation Types

1. Code Comments

• XML docs for public APIs
• Inline comments for complex logic
• TODO/FIXME for technical debt

2. API Documentation

• Endpoint descriptions
• Request/response schemas
• Error codes and handling

3. Architecture Documentation

• Component diagrams
• Data flow documentation
• Integration guides

Pattern 1: C# XML Documentation

/// <summary>
/// Saves or updates an employee entity.
/// </summary>
/// <remarks>
/// This command handles both create and update operations.
/// For new employees, the Id should be null or empty.
/// </remarks>
/// <example>
/// <code>
/// var command = new SaveEmployeeCommand
/// {
///     Name = "John Doe",
///     Email = "john@example.com"
/// };
/// var result = await handler.HandleAsync(command, cancellationToken);
/// </code>
/// </example>
public sealed class SaveEmployeeCommand : CqrsCommand<SaveEmployeeCommandResult> // project CQRS command base
{
    /// <summary>
    /// The unique identifier of the employee.
    /// Null or empty for new employees.
    /// </summary>
    public string? Id { get; set; }

    /// <summary>
    /// The employee's full name.
    /// </summary>
    /// <value>Must be non-empty and max 200 characters.</value>
    public string Name { get; set; } = string.Empty;
}

/// <summary>
/// Represents a unique expression for finding an employee.
/// </summary>
/// <param name="companyId">The company identifier.</param>
/// <param name="userId">The user identifier.</param>
/// <returns>An expression that matches the unique employee.</returns>
public static Expression<Func<Employee, bool>> UniqueExpr(string companyId, string userId)
    => e => e.CompanyId == companyId && e.UserId == userId;

Pattern 2: TypeScript JSDoc

/**
 * Manages the feature list state and operations.
 *
 * @example
 * ```typescript
 * @Component({
 *   providers: [FeatureListStore]
 * })
 * export class FeatureListComponent {
 *   constructor(private store: FeatureListStore) {
 *     store.loadItems();
 *   }
 * }
 * ```
 */
@Injectable()
export class FeatureListStore extends BaseVmStore<FeatureListState> {
  /**
   * Loads items from the API with current filters.
   *
   * @remarks
   * This effect automatically tracks loading state under the key 'loadItems'.
   * Use `isLoading$('loadItems')` to check loading status.
   *
   * @see {@link FeatureApiService.getList}
   */
  public loadItems = this.effectSimple(() => /* ... */);

  /**
   * Updates the filter criteria and resets to first page.
   *
   * @param filters - Partial filter object to merge with current filters
   *
   * @example
   * ```typescript
   * // Filter by status
   * store.setFilters({ status: FeatureStatus.Active });
   *
   * // Filter by search text
   * store.setFilters({ searchText: 'keyword' });
   * ```
   */
  public setFilters(filters: Partial<FeatureFilters>): void {
    // ...
  }
}

/**
 * Represents a feature entity from the API.
 */
export interface FeatureDto {
  /** Unique identifier */
  id: string;

  /** Display name of the feature */
  name: string;

  /**
   * Current status of the feature.
   * @default FeatureStatus.Draft
   */
  status: FeatureStatus;
}

Pattern 3: API Endpoint Documentation

/// <summary>
/// Employee management endpoints.
/// </summary>
[ApiController]
[Route("api/[controller]")]
[Authorize] // project authorization attribute (see docs/backend-patterns-reference.md)
public class EmployeeController : BaseController // project controller base
{
    /// <summary>
    /// Retrieves a paginated list of employees.
    /// </summary>
    /// <param name="query">Query parameters for filtering and pagination.</param>
    /// <returns>Paginated list of employees.</returns>
    /// <response code="200">Returns the employee list.</response>
    /// <response code="400">Invalid query parameters.</response>
    /// <response code="401">Unauthorized - authentication required.</response>
    /// <response code="403">Forbidden - insufficient permissions.</response>
    [HttpGet]
    [ProducesResponseType(typeof(GetEmployeeListQueryResult), StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
    public async Task<IActionResult> GetList([FromQuery] GetEmployeeListQuery query)
        => Ok(await Cqrs.SendAsync(query));

    /// <summary>
    /// Creates or updates an employee.
    /// </summary>
    /// <param name="command">Employee data to save.</param>
    /// <returns>The saved employee.</returns>
    /// <response code="200">Employee saved successfully.</response>
    /// <response code="400">Validation failed.</response>
    /// <response code="404">Employee not found (for updates).</response>
    [HttpPost]
    [ProducesResponseType(typeof(SaveEmployeeCommandResult), StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
    public async Task<IActionResult> Save([FromBody] SaveEmployeeCommand command)
        => Ok(await Cqrs.SendAsync(command));
}

Pattern 4: README Documentation

# Feature Name

Brief description of what this feature does.

## Overview

More detailed explanation of the feature's purpose and functionality.

## Architecture

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Frontend │────▶│ API Layer │────▶│ Domain Layer │ │ Component │ │ Controller │ │ Entity │ └─────────────────┘ └──────────────────┘ └─────────────────┘

## Usage

### Backend

// Example usage var command = new SaveFeatureCommand { Name = "Example" }; var result = await handler.HandleAsync(command, cancellationToken);

### Frontend

// Example usage this.store.loadItems();

## Configuration

| Setting | Description | Default |
| --- | --- | --- |
| `MaxItems` | Maximum items per page | 50 |
| `CacheTimeout` | Cache duration in seconds | 300 |

## API Endpoints

| Method | Endpoint | Description |
| --- | --- | --- |
| GET | `/api/feature` | List features |
| POST | `/api/feature` | Create/update feature |
| DELETE | `/api/feature/{id}` | Delete feature |

## Error Handling

| Code | Description |
| --- | --- |
| 400 | Invalid request data |
| 404 | Feature not found |
| 409 | Conflict (duplicate) |

## Related

- [Entity Documentation](https://github.com/duc01226/easyplatform/blob/HEAD/.claude/skills/tasks-documentation/./Entity.md)
- [API Reference](https://github.com/duc01226/easyplatform/blob/HEAD/.claude/skills/tasks-documentation/./API.md)

Pattern 5: Inline Code Comments

protected override async Task<SaveEmployeeCommandResult> HandleAsync(
    SaveEmployeeCommand request, CancellationToken cancellationToken)
{
    // Step 1: Determine if this is a create or update operation
    var isCreate = request.Id.IsNullOrEmpty();

    // Step 2: Get or create the entity
    var employee = isCreate
        ? request.MapToNewEntity()
            .With(e => e.CreatedBy = RequestContext.UserId())
        : await repository.GetByIdAsync(request.Id, cancellationToken)
            .EnsureFound($"Employee not found: {request.Id}")
            .Then(existing => request.UpdateEntity(existing));

    // Step 3: Validate business rules
    // NOTE: This checks for duplicate codes within the same company
    await employee.ValidateAsync(repository, cancellationToken).EnsureValidAsync();

    // Step 4: Persist changes
    // The repository automatically raises entity events for cross-service sync
    var saved = await repository.CreateOrUpdateAsync(employee, cancellationToken);

    // Step 5: Return result
    return new SaveEmployeeCommandResult
    {
        Employee = new EmployeeDto(saved)
    };
}

Documentation Guidelines

DO

• Document public APIs with XML/JSDoc
• Explain "why" not "what"
• Include usage examples
• Keep documentation close to code
• Update docs when code changes

DON'T

• State the obvious
• Leave TODO comments indefinitely
• Write documentation that duplicates code
• Create separate docs that become stale

Comment Types

Verification Checklist

• Public APIs have XML/JSDoc documentation
• Complex logic has explanatory comments
• Examples are provided where helpful
• Documentation is accurate and up-to-date
• No obvious/redundant comments
• TODO/FIXME items are actionable

IMPORTANT Task Planning Notes (MUST FOLLOW)

• Always plan and break work into many small todo tasks
• Always add a final review todo task to verify work quality and identify fixes/enhancements