Skip to main content
reopt Handbook
reopt Handbook
Agentic Documentation

Paradigm Shift

Why Documentation Must ChangeAI-readable Design PrinciplesAI-assisted Writing Process

Practice by Document Type

Project Rule DocumentsFrom Docs to Skills, Plugins, and MCPAgent Documentation SecurityAPI Docs and SpecsREADME and OnboardingArchitecture Decision RecordsRunbooks and OperationsUser Guides and TutorialsKnowledge Bases and Internal Wikis

Operations

Maintenance StrategyTeam Documentation Culture

Appendix

TemplatesVerification ReportUpdates
Handbook›에이전틱 시대의 문서화 혁신›AI-assisted Writing Process
한국어English

AI-assisted Writing Process

Source scan, draft, deterministic validation, agent smoke test, owner review, and freshness monitoring.

Key takeaways

  • AI writing works only when the workflow separates fast drafting from forced evidence, deterministic checks, and ownership.
  • The lifecycle runs source scan, design, draft, deterministic validation, agent smoke test, owner review, publish, and freshness monitoring as a loop.
  • Constrain the draft prompt to use only provided sources, forbid inventing commands, APIs, versions, or owners, and require a final "unknowns" section.
  • Run deterministic checks (links, types/build, OpenAPI lint/diff, code blocks, frontmatter, command-vs-package.json) before human review.
  • Smoke-test the document by asking an agent to use it without editing files, which catches drafting failures like hallucination, over-explanation, and date errors.

Writing documentation with AI is effective only when the workflow separates drafting from validation. The agent can draft quickly, but the team must force evidence, checks, and ownership.

Lifecycle

StepActorActivityOutput
Source scanAI + humanRead code, specs, docs, official referencesEvidence list
DesignHumanChoose surface, owner, validation, freshnessDesign sheet
DraftAIGenerate from template and sourcesMD/MDX draft
ValidationAutomationLink, schema, code block, build checksCI result
Smoke testAI + humanVerify agents can use the documentFailures
Owner reviewHumanCheck facts, security, tone, ownershipApproval
MonitorCI + ownerDetect drift and stale docsIssues

Source Scan

## Source Scan

Read:
- code: `src/api/**`, `app/api/**`
- specs: `openapi/**`, `schema/**`
- project rules: `AGENTS.md`, `CLAUDE.md`, `.claude/rules/**`
- skills: `.agents/skills/**/SKILL.md`
- official docs: [links]

Rules:
- Do not invent commands.
- Do not infer current versions without source documents.
- Mark unknowns explicitly.

Document Design Sheet

## Document Design

- Purpose:
- Primary reader: human / coding agent / RAG / MCP client
- Surface:
- Owner:
- Source of truth:
- Project-specific facts to include:
- Generic background to omit:
- Validation commands:
- Smoke test prompt:
- Freshness policy:

Draft Prompt

Write a documentation draft using only the sources below.
Do not invent commands, APIs, versions, owners, or policies.

Sources:
- [files and links]

Output:
- frontmatter
- tables and code blocks where useful
- completion criteria
- validation commands
- a final "unknowns" section

Deterministic Validation

CheckExample
Linkspnpm docs:links
Types/buildpnpm typecheck, pnpm build
OpenAPIpnpm openapi:lint, pnpm openapi:diff
Code blocksshellcheck, doctest
Frontmattercustom lint
File pathspath existence check
Commandscompare docs against package.json scripts

Agent Smoke Tests

Project rules

Assume you need to edit an API route in this repository.
Which files should you inspect and which validation commands should you run?
Do not modify files.

API docs

Using only this API document, explain how to call `POST /orders`,
including auth, request body, error handling, and any uncertainty.

Skills

Assume you are using the `release-check` Skill for the current diff.
List the commands, output format, and approval boundaries without editing files.

Common AI Drafting Failures

FailureSymptomFix
HallucinationNonexistent API or commandSource scan first
Over-explanationGeneric tutorialsState "omit generic background"
Date errorsOld facts labeled currentInclude current date and source date
Security gapsSensitive examples or broad toolsSecurity checklist
DriftDocs conflict with codeCI checks and owner review

Checklist

ItemCheck
Evidence sources are listed[ ]
Unknowns are separated from facts[ ]
Deterministic checks are included[ ]
Agent smoke test exists[ ]
Owner and freshness policy are clear[ ]

Related docs

Team Documentation Culture

Govern agent instructions, Skills, Plugins, MCP servers, ownership, and rollout.

Agent Architecture

New Brand Marketing Strategy · Design AI-assisted marketing workflows with clear roles, inputs, and review gates.

Why Documentation Must Change

From documents that are read to documents that agents can operate from.

Automation and AI

CRM Standard · Design CRM automation and AI safely without spreading bad data faster.

Governance and Collaboration

Design Systems for the AI Era · Ownership, change management, and quality gates for AI-ready design systems.

AI-readable Design Principles

Structure, density, declarative writing, navigability, and executable completion criteria.

Project Rule Documents

Design AGENTS.md, CLAUDE.md, and path-scoped rules without conflicts or drift.

On this page

LifecycleSource ScanDocument Design SheetDraft PromptDeterministic ValidationAgent Smoke TestsProject rulesAPI docsSkillsCommon AI Drafting FailuresChecklist