Documentation

Documentation

Use these patterns when writing documentation, creating runbooks, or documenting system architecture.

MCP Servers & Plugins

README Structure

# Project Name

One-line description of what this does.

## Quick Start

\`\`\`bash
npm install
npm start
\`\`\`

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| PORT | Server port | 3000 |

## Usage

[Examples of common operations]

## Development

[How to set up dev environment, run tests]

## License

MIT

API Documentation

Use OpenAPI/Swagger. Minimum per endpoint:

• HTTP method and path
• Request parameters (path, query, body)
• Response codes and schemas
• Authentication requirements
• Example request/response

Runbook Template

# [Service Name] Runbook

## Overview
What this service does, who owns it.

## Architecture
[Use `deploy-on-aws` diagram skill to generate architecture diagram]

## Health Checks
- Endpoint: `GET /health`
- Expected: 200 OK

## Common Issues

### Issue: High latency
**Symptoms**: Response times > 500ms
**Diagnosis**: Check DB connections, cache hit rate
**Resolution**: Scale horizontally, clear cache

## Escalation
- L1: On-call engineer
- L2: Service owner
- L3: Platform team

Architecture Decision Record (ADR)

# ADR-001: Use PostgreSQL for user data

## Status
Accepted

## Context
Need persistent storage for user accounts.

## Decision
Use PostgreSQL on RDS.

## Consequences
- Pro: ACID compliance, familiar tooling
- Con: Operational overhead vs DynamoDB

Spec Artifact Documentation

When documenting within the spec-driven workflow, these artifacts have defined formats (see spec-workflow skill):

When writing documentation for a project that uses the spec workflow, link to relevant specs rather than duplicating their content.

Agent Integration

• devops-agent owns READMEs, runbooks, and architecture docs — keeps them next to the code they describe
• coding-agent writes inline documentation (function/class/module docs) during implementation
• Both agents delegate to pr-review-toolkit:comment-analyzer after writing docs to verify accuracy
• sa-agent produces architecture review documentation in Well-Architected pillar format, claims and tracks tasks like other teammates
• Use github plugin to create issues for documentation that needs future updates (e.g., after API changes)

Writing Tips

• Lead with the "what" and "why"
• Use concrete examples over abstract explanations
• Keep it scannable (headers, bullets, tables)
• Update docs when code changes (or automate it)
• Docs are concise and actionable — no filler
• Use the deploy-on-aws diagram skill for architecture diagrams — don't describe what a diagram can show
• Use awslabs.document-loader-mcp-server to load external specs or references rather than copy-pasting content

Source: aws-samples/sample-claude-code-agent-team — distributed by TomeVault.