Generowanie dokumentacji z Claude Code

Minęło trzy miesiące od ostatniej aktualizacji dokumentacji. README wspomina polecenie, które zostało usunięte w ostatnim sprincie. Dokumentacja API odwołuje się do pola, które zostało przemianowane. Nowi deweloperzy zadają te same pytania onboardingowe co tydzień, ponieważ dokument architektury opisuje system sprzed dwóch refaktoryzacji. Nikt nie aktualizuje dokumentów, bo aktualizowanie dokumentów jest uciążliwe i zawsze jest pilniejsza funkcjonalność do zbudowania.

Claude Code rozwiązuje to generując dokumentację z samego kodu — nie z pamięci, nie z notatek, nie ze strony wiki, którą ktoś edytował sześć miesięcy temu. A z hookami możesz utrzymywać dokumenty w synchronizacji z każdą edycją pliku, aby nigdy więcej nie traciły aktualności.

Czego się nauczysz

• Workflow do generowania dokładnej dokumentacji z twojego faktycznego kodu
• Prompty do JSDoc/TSDoc, specyfikacji OpenAPI i dokumentów architektonicznych
• Konfiguracje hooków utrzymujących dokumentację w synchronizacji ze zmianami kodu
• Wzorce trybu headless do automatycznego generowania dokumentacji w CI

Generowanie dokumentacji z kodu

Najbardziej niezawodna dokumentacja jest generowana z kodu, który opisuje. Claude czyta twoje pliki źródłowe i tworzy dokumenty odzwierciedlające to, co kod faktycznie robi, a nie to, co ktoś pamięta, że robił.

Generowanie JSDoc i TSDoc

Wskazówka

Prompt do skopiowania — dokumentacja inline:

Read all files in src/services/ and add JSDoc comments to every
exported function, class, and type. For each one, include:

- A one-line summary of what it does
- @param for each parameter with type and description
- @returns describing the return value
- @throws for any errors the function can throw
- @example with a realistic usage example

Follow the JSDoc style already used in src/lib/database.ts.
Do not change any code logic -- only add documentation comments.

Claude czyta kod, rozumie typy z TypeScript (lub wnioskuje je z użycia w JavaScript) i pisze dokumentację pasującą do faktycznego zachowania.

Generowanie specyfikacji OpenAPI

Read all route handlers in src/routes/ and generate an
OpenAPI 3.0 specification. For each endpoint:

- HTTP method and path
- Request body schema (from the Zod validation schemas)
- Response schemas for success and error cases
- Authentication requirements
- Rate limiting headers
- Example request and response bodies

Save the spec to docs/openapi.yaml. Make it valid --
I'll run it through the OpenAPI validator after.

Dokumentacja architektury

Analyze the entire codebase and generate an ARCHITECTURE.md
that covers:

1. System overview (one paragraph)
2. Tech stack with versions
3. Directory structure with one-line descriptions
4. Key data flows (request lifecycle, background job processing)
5. External dependencies and integrations
6. How authentication works end-to-end
7. How to run, test, and deploy

Reference specific file paths. Do not describe the system
abstractly -- point to the actual code. Keep it under 200 lines.

Utrzymywanie dokumentacji w synchronizacji z hookami

Wygenerowane dokumenty są użyteczne tylko wtedy, gdy pozostają aktualne. Hooki wymuszają to automatycznie.

Hook przypominający przy zmianach dotyczących dokumentacji

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'if echo \"$FILE_PATH\" | grep -q \"src/routes/\"; then echo \"NOTE: Route file changed. Update docs/openapi.yaml if the API contract changed.\"; fi'"
      }
    ]
  }
}

Automatyczne generowanie JSDoc po edycjach plików

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'if echo \"$FILE_PATH\" | grep -qE \"\\.ts$|\\.tsx$\"; then npx tsc --noEmit \"$FILE_PATH\" 2>&1 | head -5; fi'"
      }
    ]
  }
}

Sprawdzanie świeżości dokumentacji w CI

# Run this in your CI pipeline to detect stale docs
claude -p "Compare the OpenAPI spec in docs/openapi.yaml with
the actual route handlers in src/routes/. Report any endpoints
that are documented but don't exist, or exist but aren't
documented. Also check for schema mismatches between the spec
and the Zod validation schemas." --output-format json

Dokumentowanie konkretnych obszarów kodu

Generowanie i utrzymywanie README

Wskazówka

Prompt do skopiowania — generowanie README:

Read the codebase and generate a README.md that a new developer
needs on day one. Include:

- What this project does (one paragraph, no marketing speak)
- Prerequisites (Node version, database, external services)
- Setup steps that actually work (run them to verify)
- How to run the dev server
- How to run tests
- How to deploy
- Environment variables with descriptions (don't include values)
- Project structure overview

Test every command you include by running it. If a command fails,
fix the README, not the command.

Generowanie changelogu z historii git

Read the git log between the last release tag and HEAD.
Generate a CHANGELOG entry following Keep a Changelog format:

### Added
### Changed
### Fixed
### Removed

Group by category. Write from the user's perspective, not the
developer's. "Fixed payment processing for multi-currency orders"
not "Fixed null check in payment.service.ts line 47".

Przewodniki migracji

We just released v3 of our API. Generate a migration guide
for developers upgrading from v2. Read both the v2 routes
(in src/routes/v2/) and v3 routes (in src/routes/v3/).

For each breaking change:
1. What changed
2. Why it changed
3. Before code (v2)
4. After code (v3)
5. Automated migration steps if applicable

Dokumentacja dla różnych odbiorców

Dokumentacja deweloperska (zespół wewnętrzny)

Generate internal developer documentation for the payment
module. The audience is a new team member who will be modifying
this code next week. Include:

- How the module is structured and why
- Key design decisions and their rationale
- Common gotchas and "traps" in the code
- How to test changes locally
- What to watch out for in code review

Dokumentacja dla konsumentów API (zewnętrzni deweloperzy)

Generate API documentation for external developers who will
integrate with our API. They don't know our codebase. Include:

- Getting started guide (auth, first request, response format)
- Complete endpoint reference with request/response examples
- Error codes and what they mean
- Rate limiting details
- Webhook setup and payload formats
- SDK code examples in JavaScript, Python, and curl

Dokumentacja operacyjna (DevOps/SRE)

Generate a runbook for the operations team. They need to know:

- How to deploy (and rollback) the service
- Health check endpoints and what they verify
- Key metrics to monitor and their thresholds
- Common alerts and their resolution steps
- How to debug production issues
- Database maintenance procedures

Generowanie dokumentacji w trybie headless

Zautomatyzuj generowanie dokumentacji w CI, aby dokumenty były zawsze świeże:

# Generate docs on every merge to main
claude -p "Read the codebase and update these documentation files:
1. README.md - Verify all commands still work
2. docs/openapi.yaml - Sync with current route handlers
3. docs/ARCHITECTURE.md - Update if structure changed

For each file, only modify sections that are out of date.
Do not rewrite content that is still accurate.
Report what changed." --output-format json > docs-update-report.json

Dla dokumentacji na poziomie PR:

# Check if a PR needs documentation updates
claude -p "This PR changes these files:
$(git diff --name-only main...HEAD)

Check if any documentation needs updating:
- Does the README mention anything that changed?
- Do the API docs cover any modified endpoints?
- Should the ARCHITECTURE.md be updated?

Report what needs updating and make the changes." \
  --output-format json

Używanie sub-agentów do dokumentacji

W przypadku dużych zadań dokumentacyjnych, deleguj do sub-agentów, aby każdy obszar otrzymał dokładną uwagę bez wypalania głównego kontekstu.

Use sub-agents to generate documentation for these three areas:

1. Document every exported function in src/lib/ with JSDoc
   comments. Read existing docs in the directory for style.

2. Generate a database schema document from the Prisma/Drizzle
   schema. Include table descriptions, relationships, and
   index rationale.

3. Create a testing guide that explains our test patterns,
   how to write new tests, and how to run specific test subsets.

Each sub-agent should read enough code to be accurate.
Compile the results into a single PR.

Gdy coś idzie nie tak

Wygenerowana dokumentacja jest zbyt gadatliwa. Claude ma tendencję do nadmiernego tłumaczenia. Ustaw ograniczenia: “Keep function descriptions to one sentence. Only add @example for functions with non-obvious usage. Total JSDoc for this file should not exceed 30% of the code length.”

Specyfikacja OpenAPI nie odpowiada faktycznemu zachowaniu. Claude wygenerował specyfikację z kodu handlerów tras, ale przegapił middleware transformujący zapytania lub odpowiedzi. Powiedz Claude: “Also read the middleware chain for each route. The rate limiter adds headers, the auth middleware rejects requests, and the error handler shapes error responses.”

Dokumentacja architektury natychmiast traci aktualność. Generuj ją z kodu, nie z pamięci. Gdy aktualizujesz kod, ponownie uruchom generowanie dokumentacji. Jeszcze lepiej — użyj pipeline CI do regenerowania przy każdym merge’u i zatrzymuj build, jeśli wygenerowane wyjście różni się od tego, co jest w repozytorium.

Dokumentacja powiela informacje z kodu. Dobra dokumentacja wyjaśnia dlaczego, nie co. Kod już pokazuje, co robi. Powiedz Claude: “Do not describe what the code does line by line. Explain why this approach was chosen, what the tradeoffs are, and what a developer needs to know before modifying it.”

Nikt nie czyta wygenerowanych dokumentów. Umieszczaj dokumenty tam, gdzie deweloperzy już patrzą: JSDoc wyświetla się w podpowiedziach IDE, specyfikacje OpenAPI zasilają Swagger UI, a README to pierwsza rzecz, którą ludzie widzą na GitHub. Jeśli twoje dokumenty są w oddzielnej wiki, której nikt nie odwiedza, przenieś je bliżej kodu.

Co dalej

Z wygenerowaną dokumentacją i hookami utrzymującymi ją w synchronizacji, twój kod jest gotowy na workflow backendowe, w których Claude Code radzi sobie szczególnie dobrze.

Tworzenie API Budowanie REST i GraphQL API z walidacją, uwierzytelnianiem i obsługą błędów z terminala

Analiza kodu Gdy twoja dokumentacja jest nieaktualna, użyj Claude Code do zrozumienia, co kod faktycznie robi