artubss/SKILLS-CLAUDE-CODE / favorites/tpl-situacao-documentacao-tecnica
tpl-situacao-documentacao-tecnica
VerifiedTemplate do pack (situacao/06-documentacao-tecnica.md). Orienta o agente em tarefas situacionais como debug, seguranca e refactor alinhado a esse contexto.
SITUATION: Writing Technical Documentation
Skill gerado a partir do pack templates-claude-code. Arquivo de origem: situacao/06-documentacao-tecnica.md. Use como baseline e adapte ao projeto antes de mudancas grandes.
Conteudo do template
CONTEXT
Use this configuration when writing, updating, or auditing technical documentation — including README files, Architecture Decision Records (ADRs), API documentation, runbooks, onboarding guides, data flow diagrams, and system overviews. Good documentation is code: it has an audience, a purpose, and must be maintained. The best documentation is the minimum needed to answer a reader's question.
OBJECTIVES
- Produce documentation that answers the reader's actual question, not just what's interesting to write
- Establish documentation that stays accurate over time (documentation-as-code)
- Make decisions and their rationale discoverable months after they were made
- Enable a new developer to become productive independently within their first week
APPROACH RULES
-
Audience first. Before writing, state who will read this: junior developer onboarding? DevOps engineer on-call at 2am? External API consumer? Each audience needs different information, level of detail, and vocabulary.
-
Documentation-as-code. Documentation must live in the same repository as the code. It must go through code review. It must be updated in the same PR that changes the behavior it describes.
-
Docs that go stale are worse than no docs. A wrong runbook executed at 3am causes an outage. If you can't commit to maintaining a doc, write less and make it timeless, or add a "last verified" date and owner.
-
Show, don't just describe. Every procedure should have a concrete example. Every API endpoint should have a real request/response example. Every architecture diagram should answer "what happens when X calls Y?"
-
ADR for every significant architectural decision. Did you choose Redis over Memcached? Pick PostgreSQL over MongoDB? Choose a microservice over a monolith? Write an ADR. Decisions without recorded rationale are forgotten and re-made.
-
README is the front door. Every repository needs a README that answers in under 2 minutes: what does this do, how do I run it, how do I contribute.
ROUTING TABLE
| If you encounter | Then |
|---|---|
| New repository without README | Write a README following the template below before writing any feature code |
| An architectural decision being made | Write an ADR immediately. Accepted ADRs are immutable — write a new one to supersede |
| An API endpoint being added | Write OpenAPI/Swagger spec inline. Never write API docs separately from the spec |
| A complex setup process | Write a runbook with numbered steps. Test it by following it on a clean machine |
| Business logic that's hard to understand | Write inline comments explaining WHY (the what is in the code). Link to business requirement |
| Tribal knowledge ("only Bob knows how to X") | That's a documentation emergency. Interview Bob. Write the runbook. |
| Dependency on external service behavior | Document the dependency's API version, expected behavior, and what to do if it's unavailable |
| Post-mortem / incident | Write it within 48 hours. Use blameless format. Link to it from runbook. |
| Onboarding gap reported by new hire | Treat as a bug. Fix immediately. Update onboarding guide. |
| System diagram older than 6 months | Verify it's still accurate. Update or mark as "unverified - [date]" |
README Template
# [Project Name]
> One sentence describing what this does.
## What This Does
[2-3 sentences max. What problem does this solve? What does it NOT do?]
## Prerequisites
- Node.js 20+
- PostgreSQL 15+
- [Any other hard requirement]
## Getting Started
```bash
git clone [repo]
cd [repo]
cp .env.example .env
# Edit .env with your values
npm install
npm run db:migrate
npm run dev
Project Structure
src/
api/ # HTTP route handlers
services/ # Business logic
models/ # Database models
utils/ # Shared utilities
Key Concepts
[Only the 2-3 things a new dev must understand to be productive]
Contributing
[Link to CONTRIBUTING.md or brief guide]
Documentation
## ADR Template
```markdown
# ADR-[number]: [Short Decision Title]
**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Deciders:** [Names]
## Context
[What is the problem? What constraints exist? What options were available?]
## Decision
[What was decided? Be specific.]
## Consequences
**Positive:**
- [Expected benefits]
**Negative / Tradeoffs:**
- [Known downsides we accept]
**Neutral:**
- [Side effects that are neither good nor bad]
DO NOT
- DO NOT document HOW code works — that's what the code is for. Document WHY decisions were made.
- DO NOT use passive voice in runbooks — "The service should be restarted" → "Run:
systemctl restart myservice" - DO NOT write docs that require running an external proprietary tool to read (Notion, Confluence) — keep it in the repo as Markdown
- DO NOT leave TODO items in published documentation — finish docs before merging
- DO NOT write an ADR after the fact to justify a decision already made — write it during the decision process
- DO NOT use "etc." — either list the things or don't. Vague lists lose meaning quickly.
OUTPUT FORMAT
Every documentation artifact should include a header block:
---
title: [Title]
audience: [who reads this]
last-verified: YYYY-MM-DD
owner: [team or person]
---
For runbooks, use numbered steps where order matters and bullets where it doesn't. Never mix the two in the same procedure.
For API docs, every endpoint must show:
- HTTP method + path
- Required and optional parameters with types
- At least one successful response example
- At least one error response example
QUALITY GATES
- Audience is explicitly identified at the top of every document
- Every code example is syntactically correct and has been manually tested
- README tested on a fresh machine: can someone follow it and get the project running?
- All ADRs have Status (not left as "Proposed" forever)
- No documentation references a filename, URL, or service that no longer exists
- Runbooks end with a verification step (how do you know it worked?)
- API docs match actual API behavior (tested against running service)
- Documentation updated in same PR as code change it describes
- Last-verified date set on all time-sensitive docs (runbooks, setup guides)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate 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. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |