AGENT SKILL

backend-docs

Creates selected backend Markdown documentation from code evidence, including architecture/design docs, bounded context maps, developer onboarding, API contracts, and gap analysis for code smells, project-rule violations, DDD issues, coupling, and improvement opportunities. Use when the user asks to document a backend, map backend architecture or domains, onboard backend developers, audit backend documentation gaps, or produce objective backend docs. Do NOT use for frontend docs, generic README writing, or implementing backend changes.

License 许可
MIT
所属仓库
marcioaltoe/skills
最近更新
2026-11-14
Stars
★ 0
Forks
2

01 前言 Front Matter

name
backend-docs
metadata
{ "tags": [ "documentation", "architecture", "onboarding", "ddd", "api" ], "author": "Marcio Altoé", "source": "https://github.com/marcioaltoe/skills", "version": "0.1.0", "category": "backend", "internal": false }
description
Creates selected backend Markdown documentation from code evidence, including architecture/design docs, bounded context maps, developer onboarding, API contracts, and gap analysis for code smells, project-rule violations, DDD issues, coupling, and improvement opportunities. Use when the user asks to document a backend, map backend architecture or domains, onboard backend developers, audit backend documentation gaps, or produce objective backend docs. Do NOT use for frontend docs, generic README writing, or implementing backend changes.
argument-hint
--mode <architecture|onboarding|gap-analysis|api-contracts|bounded-context> --backendPath <path-or-scope> [--outputPath <doc.md>]

02 资源文件 10

03 SKILL.md 正文

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 docs/backend/ using the template name as the filename. If the repository has a stronger docs convention, follow that convention instead.

Argument rules:

  • Treat --mode as the selected document type.
  • Treat --backendPath as the backend path, module, bounded context, route group, or scope to inspect.
  • Treat --outputPath as the requested Markdown destination.
  • If --mode is missing, infer the document type from the user's wording or ask them to choose.

Selection rules:

  • Choose bounded-context-map.md when the request mentions bounded context, domain map, subdomain, ubiquitous language, context boundary, DDD mapping, or documentation recommendations for a domain area.
  • Choose gap-analysis.md when the main outcome is risks, smells, violations, or improvement opportunities, even if DDD is one of the lenses.
  • Choose architecture-design.md 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:

  1. Project instructions: AGENTS.md, CLAUDE.md, .cursor/rules/, .windsurf/rules/, CONTRIBUTING.md.
  2. Existing docs: docs/, ADRs, RFCs, architecture notes, onboarding docs.
  3. 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 templates/.

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.

04 同仓库更多 Skills

marcioaltoe
marcioaltoe/skills

startup-validator

Comprehensive startup idea validation and market analysis tool. Use when users need to evaluate a startup idea, assess market fit, analyze competition, validate problem-solution fit, or determine market positioning. Triggers include requests to "validate my startup idea", "analyze market opportunity", "check if there's demand for", "research competition for", "evaluate business idea", or "see if my idea is viable". Provides data-driven analysis using web search, market frameworks, competitive research, and positioning recommendations.

★ 0
marcioaltoe
marcioaltoe/skills

positioning-icp

When the user wants to define their ideal customer profile, position an AI product, build messaging architecture, or validate product-market fit. Also use when the user mentions 'ICP,' 'ideal customer profile,' 'positioning,' 'PMF,' 'product-market fit,' 'messaging,' 'buyer persona,' 'enrichment signals,' 'market positioning,' or 'competitive positioning.' This skill covers market positioning, ICP definition, messaging architecture, and PMF validation for AI-native products. Do NOT use for technical implementation, code review, or software architecture.

★ 0
marcioaltoe
marcioaltoe/skills

copywriting

When the user wants to write or rewrite page copy (homepage, landing, pricing, feature), or asks which headline, promise, or message to lead with. Diagnoses the input first (blank brief, real voice, or point edit) and changes only what it calls for. Claims must be supportable; a declined claim names the evidence that would unlock it. No AI tells like 'it's not X, it's Y' or 'no X, no Y, no Z'. For editing, see copy-editing. For emails, see emails. For the offer, see offers.

★ 0
marcioaltoe
marcioaltoe/skills

business-storyteller

Transforms technical work into persuasive business-language documents for non-technical stakeholders, including internal announcements, approval proposals, incident explainers, technical-debt cases, product explainers, and investor or partner memos. Use when the user asks to present technical work to the company, explain software to business teams, write a business case, make an approval document, or convert a technical artifact into stakeholder communication in the requested language. Do not use for READMEs, specs, ADRs, external marketing pages, or customer-facing sales copy.

★ 0
marcioaltoe
marcioaltoe/skills

brand-storytelling

Help users craft compelling brand narratives. Use when someone is defining brand strategy, writing company positioning, creating pitch narratives, developing messaging frameworks, or trying to make their company story more memorable.

★ 0
marcioaltoe
marcioaltoe/skills

skill-creator

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

★ 0