Backend Documentation
Create objective Markdown documentation for backend systems from code evidence. Generate only the document type the user selects; do not create a full documentation set unless explicitly requested.
Document Selection
If the user does not specify the document type, ask them to choose one or more:
| User need | Template |
|---|
| Architecture and backend design | templates/architecture-design.md
|
| Developer onboarding | templates/developer-onboarding.md
|
| Gap analysis and improvement opportunities | templates/gap-analysis.md
|
| API contracts and endpoint behavior | templates/api-contracts.md
|
| Bounded context map and DDD documentation | templates/bounded-context-map.md
|
If the user asks for "backend docs" without a target path, create the selected file under
using the template name as the filename. If the repository has a stronger docs convention, follow that convention instead.
Argument rules:
- Treat as the selected document type.
- Treat as the backend path, module, bounded context, route group, or scope to inspect.
- Treat as the requested Markdown destination.
- If is missing, infer the document type from the user's wording or ask them to choose.
Selection rules:
- Choose when the request mentions bounded context, domain map, subdomain, ubiquitous language, context boundary, DDD mapping, or documentation recommendations for a domain area.
- Choose when the main outcome is risks, smells, violations, or improvement opportunities, even if DDD is one of the lenses.
- Choose when the main outcome is how the backend is structured or why it is designed that way.
- Ask a clarifying question only when two document types would produce materially different outputs and the prompt does not imply a stronger reader need.
Workflow
Step 1: Confirm Scope
Identify the target backend, module, service, bounded context, or route group. If the request is broad, document only the highest-value slice first and note what remains out of scope.
Capture:
- Document type and target reader.
- Target path or docs convention.
- Backend stack and runtime if discoverable.
- Whether the document should describe current state, proposed design, or both.
Step 2: Discover Rules and Existing Docs
Read
references/discovery-workflow.md
, then inspect project rules before reading implementation details.
Prioritize:
- Project instructions: , , , , .
- Existing docs: , ADRs, RFCs, architecture notes, onboarding docs.
- Code contracts: route definitions, schemas, generated OpenAPI setup, database schemas, migrations, jobs, queues, integrations, tests.
If project rules conflict with this skill, project rules win.
Step 3: Gather Evidence From Code
Trace the backend from entry points to behavior. Use file references rather than pasting large code blocks.
Look for:
- App bootstrapping, dependency injection, routing, middleware, auth, and tenancy.
- Controllers, handlers, use cases, services, domain models, repositories, data access, and external clients.
- API request and response schemas, error shapes, status codes, generated documentation, and client contracts.
- Database tables, relationships, migrations, transactions, backfills, and unsafe migration patterns.
- Background jobs, webhooks, queues, event flows, scheduled tasks, retries, idempotency, and failure handling.
- Tests, observability, runbooks, feature flags, rollback paths, and operational risks.
Document facts as "Observed" and label conclusions as "Inference" when they are not directly stated in code or docs.
Step 4: Load Only Relevant References
Use progressive disclosure:
- For documentation structure and brevity, read
references/documentation-principles.md
- For backend evidence collection and source-skill routing, read
references/source-skill-map.md
- For architecture, API, DDD, coupling, data, and quality checks, read
references/backend-quality-lenses.md
- For Hono, Zod/OpenAPI, Drizzle, schema validation, generated API docs, or migration evidence, read
references/framework-contract-notes.md
- For the selected document shape, read only the matching template in .
Step 5: Write the Markdown Document
Use the selected template as the structure. Keep the document compact and useful to the target reader.
Each generated document should:
- Start with scope, audience, and last-reviewed date.
- Cite concrete code or docs evidence with file paths and line numbers when available.
- Separate current state from recommendations.
- Prefer tables for inventories, risks, APIs, gaps, and next actions.
- Include diagrams only when they clarify relationships or runtime flow.
- Mark unknowns and assumptions instead of inventing missing details.
- End with a short maintenance note explaining when the document should be updated.
Step 6: Validate Before Finishing
Before final response:
- Re-read the generated or edited document.
- Check that the selected template was followed.
- Check that every non-obvious claim has evidence or is labeled as inference.
- Check that no unrelated templates were generated.
- Check links and file paths.
- If validation commands exist for docs formatting or markdown linting, run the project-preferred command.
Output Rules
- Write in the user's language unless the repository has a documented docs language.
- Use concise technical prose. Avoid promotional language and generic claims.
- Do not duplicate large source code blocks. Link to source paths instead.
- Do not silently create ADRs, RFCs, or TDDs unless the user selected that form or the repository convention requires it.
- Do not implement backend changes while documenting. If gaps are found, record them as recommendations.
Examples
Architecture and Design
User says: "Document the backend architecture for the billing service."
Action: Select
templates/architecture-design.md
, inspect project rules and billing code, map components and runtime flows, then write one Markdown document with current architecture, decisions, risks, and improvement opportunities.
Onboarding
User says: "Create onboarding docs so a new backend dev can understand this API."
Action: Select
templates/developer-onboarding.md
, identify setup commands and core flows from project docs and code, then write a practical guide that gets the reader from local setup to safe first contribution.
Gap Analysis
User says: "Find backend documentation gaps and architecture smells in this module."
Action: Select
templates/gap-analysis.md
, apply project rules plus DDD, coupling, API, data, and testing lenses, then produce prioritized findings with evidence, severity, and next actions.
Bounded Context Map
User says: "Map the auth bounded context and recommend backend docs we should add."
Action: Select
templates/bounded-context-map.md
, apply the domain-analysis, tactical-DDD, coupling, API, data, and project-rule lenses, then produce one context map with boundaries, relationships, model ownership, risks, unknowns, and documentation recommendations.