Claude Code से documentation generation: README, API spec, ADR और verification
Claude Code से README, OpenAPI, ADR और changelog बनाएं और Node scripts से उन्हें verify करें।
Documentation generation में सबसे जरूरी चीज evidence है
README, API specification, ADR और changelog अक्सर code से पीछे रह जाते हैं। Feature बनता है, tests लिखे जाते हैं, deploy होता है, लेकिन documentation बाद में करने वाली चीज बन जाती है। कुछ समय बाद नया developer repository clone करता है और पाता है कि README का command काम नहीं करता, या API docs में लिखा response असली response से अलग है।
Claude Code इस काम को तेज कर सकता है। Official Claude Code overview बताता है कि Claude Code codebase पढ़ सकता है, files edit कर सकता है और commands चला सकता है। यही ताकत documentation के लिए उपयोगी है, लेकिन बिना evidence के यही risk भी बनती है। Claude Code बहुत साफ भाषा में ऐसा command या endpoint लिख सकता है जो project में है ही नहीं।
इसलिए workflow का लक्ष्य सिर्फ “अच्छी documentation लिखना” नहीं है। लक्ष्य है: पहले repository context बनाना, फिर Claude Code को limited documentation task देना, फिर generated files को script से verify करना। अगर आपको final proof record भी चाहिए, तो Claude Code verification receipt workflow साथ में पढ़ें।
पूरा workflow: context, generation, verification, human decision
“README improve करो” बहुत खुला prompt है। Claude Code अनुमान लगा सकता है। बेहतर तरीका है कि पहले package.json, git diff, recent commits और existing docs से एक छोटा context बनाया जाए। उसी context के आधार पर README, OpenAPI, ADR और CHANGELOG update कराए जाते हैं।
flowchart LR
A["Code diff"] --> B["doc-context.mjs"]
B --> C["Claude Code skill"]
C --> D["README / OpenAPI / ADR / CHANGELOG"]
D --> E["verify-docs.mjs"]
E --> F["Human publish decision"]
ADR का मतलब Architecture Decision Record है। यह एक छोटा note होता है जिसमें लिखा जाता है कि कोई technical decision क्यों लिया गया। OpenAPI API routes, request और response को ऐसे format में लिखता है जिसे बाद में check किया जा सके। Beginners के लिए बात सरल है: documentation सुंदर दिखने से ज्यादा जरूरी है कि वह verify हो सके।
Repository context generate करना
नीचे दिया गया script scripts/doc-context.mjs के रूप में save करें और repository root से node scripts/doc-context.mjs चलाएं। यह docs/_generated/doc-context.md बनाता है।
import { execSync } from "node:child_process";
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import path from "node:path";
function run(command) {
try {
return execSync(command, {
encoding: "utf8",
stdio: ["ignore", "pipe", "pipe"],
}).trim();
} catch {
return "";
}
}
function readIfExists(filePath) {
return existsSync(filePath) ? readFileSync(filePath, "utf8") : "";
}
const root = process.cwd();
const outDir = path.join(root, "docs", "_generated");
mkdirSync(outDir, { recursive: true });
const packageJson = readIfExists("package.json");
const packageSummary = packageJson
? JSON.stringify(JSON.parse(packageJson).scripts ?? {}, null, 2)
: "{}";
const fence = String.fromCharCode(96, 96, 96);
const trackedFiles = run("git ls-files")
.split(/\r?\n/)
.filter(Boolean)
.filter((file) => !file.startsWith("node_modules/"))
.filter((file) => !file.startsWith("dist/"))
.filter((file) => !file.startsWith(".git/"))
.slice(0, 400);
const changedFiles = run("git status --short") || "(no uncommitted changes)";
const recentCommits = run("git log --oneline -8") || "(no commits found)";
const content = [
"# Documentation Context",
"",
"## Package scripts",
`${fence}json`,
packageSummary,
fence,
"",
"## Changed files",
`${fence}text`,
changedFiles,
fence,
"",
"## Recent commits",
`${fence}text`,
recentCommits,
fence,
"",
"## Tracked file sample",
`${fence}text`,
trackedFiles.join("\n"),
fence,
"",
].join("\n");
const outFile = path.join(outDir, "doc-context.md");
writeFileSync(outFile, content);
console.log(`Wrote ${outFile}`);
यह file public documentation नहीं है। यह Claude Code के लिए working context है। इसे docs/_generated में रखने से generated evidence और reader-facing docs अलग रहते हैं।
Documentation refresh के लिए Claude Code skill
Claude Code में repeatable workflow को skill में रखा जा सकता है। Official skills and slash commands documentation बताता है कि SKILL.md से /docs-refresh जैसा command बनाया जा सकता है। पुराने .claude/commands/ भी काम करते हैं।
.claude/skills/docs-refresh/SKILL.md बनाएं:
---
description: Refresh README, OpenAPI, ADR, and changelog from current code and generated documentation context.
---
## Inputs to inspect first
- Repository context: @docs/_generated/doc-context.md
- README: @README.md
- Existing docs: @docs
- Package metadata: @package.json
## Task
Update documentation only where the current code, package scripts, or git diff prove that the text is stale.
Required outputs:
1. README: setup steps, commands, environment notes, and troubleshooting.
2. OpenAPI: update `docs/api/openapi.yaml` when API routes changed.
3. ADR: create `docs/adr/NNNN-short-title.md` when a new architectural decision is visible.
4. CHANGELOG: add a draft entry under `Unreleased` when user-facing behavior changed.
Rules:
- Do not invent endpoints, commands, environment variables, prices, or dates.
- If evidence is missing, write a short "needs confirmation" note instead of guessing.
- Keep secret names generic. Never copy `.env` values into docs.
- After editing, run `node scripts/verify-docs.mjs` and report the result.
यहां “documentation only” बहुत महत्वपूर्ण है। Claude Code implementation files भी edit कर सकता है, इसलिए docs task को docs तक ही सीमित रखना चाहिए। Team setup में Claude Code permissions guide पढ़कर allowed commands और sensitive files तय करें।
Use case 1: README को onboarding guide बनाना
README project का प्रचार पेज नहीं है। यह उस व्यक्ति की मदद करता है जिसने अभी repository clone किया है। उसे install, run, test, common errors और next docs चाहिए।
# Task API
## Getting started
```bash
npm ci
npm run dev
```
## Commands
| Command | Purpose |
| --- | --- |
| `npm run dev` | Start the local server |
| `npm run test` | Run unit tests |
| `npm run docs:context` | Generate documentation context |
| `npm run docs:verify` | Verify documentation files |
## Troubleshooting
- If install fails, delete `node_modules` and run `npm ci` again.
- If API examples fail, confirm the server is running on the documented port.
- If generated docs mention unknown env vars, check `.env.example`, not `.env`.
Claude Code को “clear बनाओ” कहने की जगह “fresh clone करने वाले developer के लिए लिखो” कहना ज्यादा उपयोगी output देता है।
Use case 2: API docs को OpenAPI में रखना
API docs अगर सिर्फ prose में हों तो verify करना मुश्किल होता है। Claude Code को routes, validation schemas और tests पढ़ाकर docs/api/openapi.yaml update कराएं।
openapi: 3.1.0
info:
title: Task API
version: 0.1.0
description: API for creating and listing tasks.
paths:
/api/tasks:
get:
summary: List tasks
responses:
"200":
description: Task list
content:
application/json:
schema:
type: object
properties:
tasks:
type: array
items:
type: object
required: [id, title, status]
properties:
id:
type: string
title:
type: string
status:
type: string
enum: [todo, doing, done]
post:
summary: Create a task
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [title]
properties:
title:
type: string
responses:
"201":
description: Created task
यहां common pitfall overcompletion है। अगर real API open लौटाती है और spec todo लिखता है, तो सुंदर spec भी गलत है।
Use case 3: ADR में decision reason बचाना
ADR task log नहीं है। इसमें context, decision और consequences लिखे जाते हैं।
# ADR-0001: Keep generated documentation under docs/_generated
## Status
Accepted
## Context
Claude Code needs a compact summary of the repository before refreshing documentation.
Putting generated context beside hand-written docs can confuse reviewers.
## Decision
Generated context files will be written to `docs/_generated/`.
Hand-written documentation stays in `docs/api`, `docs/adr`, and root README files.
## Consequences
- Reviewers can separate generated context from authored documentation.
- The context file can be regenerated before each documentation refresh.
- The verification script must ignore unstable generated content when checking prose quality.
Claude Code draft बना सकता है, लेकिन final reason human team को confirm करना चाहिए। ADR future में decision का record बनता है।
Use case 4: CHANGELOG को Unreleased में draft करना
CHANGELOG release day पर memory से लिखना risk है। Claude Code को current diff से Unreleased के नीचे draft लिखवाएं और version/date confirm होने तक खाली रखें।
# Changelog
## Unreleased
### Added
- Added documentation context generation for README, API specs, ADRs, and changelog updates.
### Changed
- Updated the documentation refresh workflow to verify generated files before publication.
### Needs confirmation
- Confirm the final release version and release date before moving this entry out of `Unreleased`.
इससे information बचती है, लेकिन release होने का झूठा दावा नहीं होता।
Generated docs verify करने वाला script
नीचे दिया गया script scripts/verify-docs.mjs के रूप में save करें। यह required files, required phrases, ADR headings, code fences और obvious placeholders check करता है।
import { existsSync, readdirSync, readFileSync } from "node:fs";
import path from "node:path";
const requiredFiles = [
{
file: "README.md",
phrases: ["## Getting started", "## Commands"],
},
{
file: "docs/api/openapi.yaml",
phrases: ["openapi: 3.", "paths:"],
},
{
file: "CHANGELOG.md",
phrases: ["## Unreleased"],
},
];
function read(file) {
return readFileSync(file, "utf8");
}
function listMarkdownFiles(dir) {
if (!existsSync(dir)) return [];
return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
const fullPath = path.join(dir, entry.name);
if (entry.isDirectory()) return listMarkdownFiles(fullPath);
return entry.isFile() && /\.(md|mdx)$/.test(entry.name) ? [fullPath] : [];
});
}
const errors = [];
for (const item of requiredFiles) {
if (!existsSync(item.file)) {
errors.push(`${item.file}: missing file`);
continue;
}
const source = read(item.file);
for (const phrase of item.phrases) {
if (!source.includes(phrase)) {
errors.push(`${item.file}: missing phrase "${phrase}"`);
}
}
}
for (const adr of listMarkdownFiles("docs/adr")) {
const source = read(adr);
for (const heading of ["## Status", "## Context", "## Decision", "## Consequences"]) {
if (!source.includes(heading)) {
errors.push(`${adr}: missing ${heading}`);
}
}
}
for (const file of ["README.md", "CHANGELOG.md", ...listMarkdownFiles("docs")]) {
if (!existsSync(file)) continue;
const source = read(file);
const fenceMarker = String.fromCharCode(96, 96, 96);
const fenceCount = (source.match(new RegExp(fenceMarker, "g")) ?? []).length;
if (fenceCount % 2 !== 0) errors.push(`${file}: unbalanced code fence`);
if (/TODO|TBD|REPLACE_ME/.test(source)) {
errors.push(`${file}: unresolved placeholder remains`);
}
}
if (errors.length > 0) {
console.error("Documentation verification failed:");
for (const error of errors) console.error(`- ${error}`);
process.exit(1);
}
console.log("Documentation verification passed.");
package.json में commands जोड़ें:
{
"scripts": {
"docs:context": "node scripts/doc-context.mjs",
"docs:verify": "node scripts/verify-docs.mjs"
}
}
Official settings documentation project और local settings अलग रखने का तरीका बताती है। शुरुआत में docs scripts allow करें और secrets deny करें।
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(node scripts/doc-context.mjs)",
"Bash(node scripts/verify-docs.mjs)",
"Read(README.md)",
"Read(docs/**)",
"Read(src/**)"
],
"deny": [
"Read(.env)",
"Read(.env.*)",
"Read(secrets/**)",
"Bash(curl *)"
]
}
}
File edit के बाद automatic check चाहिए तो official hooks reference पढ़ें। लेकिन पहले manual run से सीखें कि कौन सी failure सच में block करनी चाहिए।
Common pitfalls
पहली गलती है nonexistent command लिखना। README commands हमेशा package.json, Makefile या CI से confirm करें।
दूसरी गलती है API behavior invent करना। OpenAPI सुंदर हो सकती है, फिर भी गलत हो सकती है।
तीसरी गलती है secrets leak करना। .env, tokens, customer names और internal URLs docs में नहीं आने चाहिए।
चौथी गलती है internal context को public docs बनाना। docs/_generated/doc-context.md Claude Code input है, user manual नहीं।
पांचवीं गलती है verification को अंत में formal step मानना। diff छोटा हो तभी docs:context और docs:verify चलाएं।
Templates, products और consultation path
Solo project में ये दो Node scripts और docs-refresh skill काफी हैं। Long-term project rules के लिए CLAUDE.md best practices guide के साथ use करें।
Daily commands हाथ में रखने के लिए free Claude Code cheat sheet अच्छा starting point है। अगर README, review, debugging और docs prompts बार-बार लिखने पड़ते हैं, तो Gumroad template pack time बचाता है।
Team adoption में main question यह होता है कि final approval कौन करेगा, कौन सा docs error publish रोकता है, और Gumroad या consultation CTA कैसे verify होंगे। ऐसे workflow के लिए implementation consultation में real repository के आधार पर rules बनाना बेहतर है।
मैंने इसे आजमाकर क्या पाया
मैंने पहले doc-context.md generate किया, फिर README, OpenAPI, ADR और CHANGELOG को अलग जिम्मेदारी के रूप में Claude Code को दिया, और अंत में verify-docs.mjs चलाया। सीधे “README लिखो” कहने की तुलना में fake commands कम आए और ADR में decision reason साफ रहा। API spec के लिए फिर भी real response से human comparison जरूरी है। Best result full automation नहीं, बल्कि fast draft, visible evidence और clear verification stop है।
मुफ़्त PDF: Claude Code cheatsheet
Email डालें और commands, review habits तथा safe workflow वाली एक-page PDF पाएँ.
हम आपका data सुरक्षित रखते हैं और spam नहीं भेजते.
लेखक के बारे में
Masa
Claude Code workflow और team adoption पर काम करने वाला engineer.
संबंधित लेख
Claude Code permission safety ladder: access धीरे-धीरे बढ़ाएं
read-only से limited edits, proof commands और deploy checks तक permission बढ़ाने की सुरक्षित ladder.
Claude Code Small PR Proof Pack: छोटे PR को review-ready बनाना
Claude Code PR के लिए diff, checks, public URL, CTA path और rollback वाला practical proof pack.
Claude Code Review Gate Before Commit: diff, test, public URL और CTA जांच
Claude Code से commit से पहले review gate बनाएं: diff, build, public URL, Gumroad, consultation, tests और unrelated files।