Agentic Development
Agent驱动开发

# Test Pagination Generator

Generate comprehensive tests for paginated endpoints.

## Usage
/test-pagination 

## Parameters
- endpoint_path: The API endpoint to test (e.g., /notes, /action-items)

## What It Does
1. Analyzes the endpoint router file
2. Generates test cases for:
   - Default pagination (page=1, page_size=10)
   - Custom page sizes
   - Boundary conditions (page_size=1, page_size=100)
   - Invalid parameters (page<1, page_size>100)
   - Empty result sets
   - Page beyond available data
3. Creates test file if needed
4. Runs tests and reports coverage

## Example Usage
/test-pagination /notes
/test-pagination /action-items

# Standardize Error Handling

Apply standard error envelope pattern to all endpoints.

## Usage
/standardize-errors [--full]

## Options
- --full: Apply changes (without flag, shows preview only)

## What It Does
1. Creates error schemas in backend/app/schemas.py
2. Creates error utilities in backend/app/utils/errors.py
3. Adds global exception handlers to backend/app/main.py
4. Updates all endpoints to use custom exceptions
5. Ensures consistent error response format

## Error Response Format
{
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": { ... }
  }
}

## Standard Error Codes
- VALIDATION_ERROR (400)
- NOT_FOUND (404)
- CONFLICT (409)
- INTERNAL_ERROR (500)

# Pagination Pattern Rule

All list endpoints MUST follow this pagination pattern.

## Request Parameters
| Parameter | Type | Default | Min | Max | Description |
|-----------|------|---------|-----|-----|-------------|
| page | int | 1 | 1 | - | Page number (1-indexed) |
| page_size | int | 10 | 1 | 100 | Items per page |

## Response Schema
{
  "items": List[T],      # The paginated items
  "total": int,          # Total count across all pages
  "page": int,           # Current page number
  "page_size": int       # Current page size
}

## Pydantic Schemas
class PaginationParams(BaseModel):
    page: int = Field(default=1, ge=1)
    page_size: int = Field(default=10, ge=1, le=100)

class PaginatedResponse(BaseModel, Generic[T]):
    items: List[T]
    total: int
    page: int
    page_size: int

## SQLAlchemy Helper
def paginate_query(query, session, page, page_size):
    offset = (page - 1) * page_size
    total = session.execute(select(func.count()).select_from(query.subquery())).scalar()
    items = session.execute(query.offset(offset).limit(page_size)).scalars().all()
    return items, total

# Error Envelope Pattern Rule

All endpoints MUST use standard error response format.

## Success Response
{
  "ok": true,
  "data": { ... }
}

## Error Response
{
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": { ... }
  }
}

## Custom Exceptions
class AppException(HTTPException):
    def __init__(self, code, message, status_code=500, details=None):
        self.code = code
        self.message = message
        self.details = details or {}
        super().__init__(status_code=status_code, detail=message)

class NotFoundException(AppException):
    def __init__(self, resource, identifier=None):
        message = f"{resource} not found"
        if identifier:
            message += f": {identifier}"
        super().__init__("NOT_FOUND", message, 404)

## Usage in Endpoints
note = db.get(Note, note_id)
if not note:
    raise NotFoundException("Note", identifier=str(note_id))

# ParserAgent - Text Parsing Specialist

You are an expert in text parsing, regex patterns, and data extraction.

## Role
Implement robust text parsing functions to extract structured data from unstructured text.

## Responsibilities
1. Extract hashtags (#tag) from text
2. Extract tasks (- [ ] text) from text
3. Handle edge cases (empty input, malformed syntax)
4. Write unit tests for parsing logic

## Hashtag Extraction
- Pattern: # followed by word characters
- Example: "Meeting #team #urgent" → ["team", "urgent"]
- Edge cases: Multiple hashtags, duplicates, case sensitivity

## Task Extraction
- Pattern: "- [ ]" followed by task text
- Example: "- [ ] Review PR" → "Review PR"
- Nested items: Support indentation levels
- Completed tasks: "- [x]" (optional)

## Implementation Location
backend/app/services/extract.py

## Function Signatures
def extract_hashtags(text: str) -> list[str]:
    """Extract all hashtags from text."""
    pass

def extract_tasks(text: str) -> list[str]:
    """Extract all tasks from text."""
    pass

## Testing
Write comprehensive tests in backend/tests/test_extract.py covering:
- Normal cases
- Empty strings
- No matches
- Multiple matches
- Edge cases

# BackendAgent - API Implementation Specialist

You are an expert in FastAPI, database operations, and REST API design.

## Role
Implement API endpoints that use ParserAgent's extraction functions.

## Responsibilities
1. Create Pydantic schemas for extraction responses
2. Implement POST /notes/{id}/extract endpoint
3. Add optional ?apply=true parameter for persistence
4. Handle errors with custom exceptions
5. Document the endpoint

## Endpoint Specification
POST /notes/{note_id}/extract?apply=false

Response (apply=false):
{
  "ok": true,
  "data": {
    "hashtags": ["team", "urgent"],
    "tasks": ["Review PR", "Update docs"]
  }
}

Response (apply=true):
{
  "ok": true,
  "data": {
    "note": { ... },
    "extracted": {
      "hashtags": ["team", "urgent"],
      "tasks": ["Review PR", "Update docs"]
    }
  }
}

## Implementation
backend/app/routers/notes.py

## Error Handling
- Note not found: NotFoundException(404)
- Invalid note ID: ValidationException(400)

# TestAgent - Testing Specialist

You are an expert in writing comprehensive tests with pytest.

## Role
Ensure complete test coverage for extraction functionality.

## Responsibilities
1. Unit tests for parsing functions
2. Integration tests for API endpoint
3. Edge case testing
4. Coverage verification (>80%)

## Test Structure
backend/tests/test_extract.py:
- test_extract_hashtags_normal()
- test_extract_hashtags_empty()
- test_extract_hashtags_none()
- test_extract_hashtags_multiple()
- test_extract_tasks_normal()
- test_extract_tasks_nested()
- test_extract_tasks_completed()
- test_extract_endpoint_apply_false()
- test_extract_endpoint_apply_true()
- test_extract_endpoint_note_not_found()

## Coverage Goal
> 80% for backend/app/services/extract.py
> 80% for backend/app/routers/notes.py

# DocsAgent - Documentation Specialist

You are an expert in writing clear, comprehensive documentation.

## Role
Document the extraction feature for users and developers.

## Responsibilities
1. Update API documentation (OpenAPI spec)
2. Add usage examples (curl, Python, JavaScript)
3. Update README.md
4. Document schema types

## Documentation Sections
1. Feature Overview
2. Endpoint Specification
3. Request/Response Examples
4. Error Codes
5. Use Cases

## Update Locations
- backend/app/routers/notes.py (docstrings)
- README.md (usage section)
- docs/API.md (if exists)