Documentation and Onboarding Agents for Codebases
Documentation agents read the repository as it is - packages, entrypoints, configs, tests - and produce or maintain human-oriented explanations.
Onboarding agents use the same grounding to answer "how do I run X?" without inventing APIs that do not exist.
How to Use This List
- Use tables when designing a docs bot, onboarding buddy, or doc-refresh job.
- Prefer grounded answers with file citations over polished uncited prose.
- Start read-only; only grant write access to docs paths you review.
- Re-run stale-doc audits after major refactors, not only on a calendar.
A - Jobs These Agents Do Well
| Job | Output | Success signal |
|---|---|---|
| Architecture sketch | Service/module map with paths | Engineers agree it matches reality |
| Runbook / how-to | Step list with exact commands | New hire completes task unassisted |
| API surface notes | Endpoint/function summary | Matches OpenAPI/types/tests |
| Changelog draft | PR or release notes from diffs | Maintainers accept with light edit |
| Stale doc detect | List of docs vs code mismatches | High precision on flagged pages |
| Onboarding Q&A | Cited answers in chat | Low "wrong command" rate |
B - Grounding Sources (Priority Order)
| Source | Why | Risk if ignored |
|---|---|---|
| Runnable entrypoints | main, scripts, Makefile, package.json | Docs invent wrong start commands |
| Types / schemas / OpenAPI | Contract truth | Narrative drifts from API |
| Tests and fixtures | Executable examples | Tutorials that cannot work |
| CI config | Real quality gates | Onboarding skips required checks |
| Existing docs | Voice and coverage map | Duplicate conflicting pages |
| CODEOWNERS / package layout | Ownership and boundaries | Cross-team confusion |
| Issue templates / ADRs | Intent and history | "Why" answers become guesses |
C - Read vs Write Modes
| Mode | Rights | Use when… |
|---|---|---|
| Answer-only | Read repo + search | Onboarding chat, support |
| Draft docs PR | Write under docs/** only | Scheduled refresh, new modules |
| Inline comment refresh | Write code comments | Strict style guide + review |
| Full mixed write | Code + docs | Rare; high review cost |
D - Onboarding Question Cheatsheet
| Question type | Agent should… | Agent should not… |
|---|---|---|
| How do I run locally? | Cite Makefile/README/scripts | Guess ports or magic env vars |
| Where is feature X? | Link paths + owners | Dump half the monorepo |
| How do I test my change? | Exact CI-equivalent commands | Invent one-off flags |
| What is our auth model? | Point to middleware + docs | Over-simplify security |
| Who do I ask? | CODEOWNERS / team map | Name random git blame authors as owners |
E - Doc Generation Patterns
| Pattern | Description | Watch-outs |
|---|---|---|
| Map then draft | Build module graph, then prose | Graph wrong → pretty wrong docs |
| Diff-to-notes | Summarize PR for humans | Misses unstated intent |
| Docstring fill | Generate function docs from signature + body | Lies about side effects |
| Tutorial from tests | Turn integration tests into guides | Overfits test doubles |
| Compare stale | Embed/hash docs vs code symbols | False positives on narrative docs |
F - Citation and Trust Rules
| Rule | Practice |
|---|---|
| Cite paths | Every procedural step references a file or command source |
| Prefer commands from repo | Copy from scripts/CI, do not paraphrase into poetry |
| Label uncertainty | "Not found in repo; verify with owner" beats confident fiction |
| No secret leakage | Redact .env samples that contain real credentials |
| Version the advice | Note branch/commit when answers are environment-sensitive |
G - Freshness and Ownership
| Practice | Why |
|---|---|
| Docs PRs on package change | Keeps narrative near code change |
| OWNERS for docs paths | Someone must review agent drafts |
| Quarterly dead-link + command audit | Catches rot automation misses |
| Deprecate pages explicitly | Agents should not revive dead stacks |
| Single source for commands | DRY: docs link to scripts rather than fork them |
H - Anti-Patterns
| Anti-pattern | Failure mode | Prefer |
|---|---|---|
| Uncited long essays | Plausible fiction | Short, sourced bullets |
| Regenerating whole wiki weekly | Review fatigue; thrash | Targeted stale modules |
| Writing secrets "for completeness" | Credential leaks | Placeholder env templates |
| Docs that re-implement logic | Double maintenance | Point to code + high-level why |
| Onboarding agent with prod credentials | Security incident | Local/dev scopes only |
| Treating chat history as source of truth | Drift | Always re-read repo |
I - Minimal Evaluation Set
| Check | Pass looks like |
|---|---|
| Cold start | New clone; agent answers "run tests" correctly |
| Wrong path trap | Agent refuses outdated folder names after rename |
| Command accuracy | 10 sampled how-tos execute cleanly |
| Citation presence | ≥90% of procedural answers include paths |
| Stale flag precision | Engineers agree most flags are real issues |
| Time-to-first-success | New hire metric improves vs doc-only baseline |
J - What to Put in a Repo Rules File for Docs Agents
| Section | Content |
|---|---|
| Doc roots | Where new pages may be added |
| Command sources of truth | Makefile targets, taskfiles, package scripts |
| Forbidden topics | Prod credentials, customer data examples |
| Voice | Imperative steps, short paragraphs |
| Link style | Relative paths your site/docs system accepts |
| Reviewers | Always request review from package owners |
FAQs
Are documentation agents "coding agents"?
They are developer-tooling agents. Many share read/search tools with coding agents but should default to narrower write scopes.
Should the agent edit code comments or only markdown?
Start with markdown/docs sites. Inline comments change review load and can spam diffs.
How do we stop hallucinated setup steps?
Require citations, verify commands in CI when possible, and refuse when sources are missing.
Can one agent onboard across a huge monorepo?
Route by package path and ownership. A single global brain without routing drowns in context.
How often should docs be regenerated?
On relevant code changes plus periodic stale audits. Blind full regenerations create thrash.
Do we still need human technical writers?
Yes for narrative, audience design, and prioritization. Agents draft and detect drift.
What about diagrams?
Agents can draft Mermaid or similar from module graphs. Humans validate accuracy before publishing.
Should onboarding answers be cached?
Cache with commit SHA invalidation. Stale caches are how wrong ports live forever.
How do docs agents interact with RAG?
RAG over docs helps Q&A, but generation and staleness checks still need live code tools - pure doc RAG will lag the repo.
Is auto-merging doc PRs safe?
Only for low-risk formatting. Content changes need owners, especially security and ops pages.
What is a good first pilot?
Read-only Q&A for one service plus a weekly draft PR that updates that service's README from code and tests.
How do we measure onboarding impact?
Time-to-first-productive PR, frequency of "how do I run" questions, and accuracy audits of agent answers.
Related
- How Coding Agents Changed Day-to-Day Software Development - docs as agent policy inputs
- Coding & Developer-Tooling Use Cases Basics - repo tools and task packaging
- Code Review Agents: Automated PR Feedback at Scale - another PR-time developer agent
- DevOps Agents: Deployment, Incident Triage, and Runbook Execution - runbooks as operational docs
- Coding & Developer-Tooling Use Cases Best Practices - scoping access and review
Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana
@solana/web3.js+@solana/spl-token.