In many development and infrastructure teams, documentation is still the weakest part of the project. The code evolves, environments change, new integrations appear, deployment steps shift, and yet the docs are often left behind. The result is familiar: slow onboarding, avoidable mistakes, too much dependence on one or two key people, and AI coding agents that start with incomplete or outdated context.

That is where a well-designed prompt can make a meaningful difference. Not because it replaces technical judgment, but because it allows tools such as Claude Code — or similar repo-aware assistants — to act like a documentation auditor, capable of comparing what the project says about itself with what the code actually does.

The prompt below is aimed precisely at that problem. It is not a vague “summarize this repo” request, and it is not just “improve the README.” It is a structured operational instruction that forces the assistant to inventory the existing docs, inspect the real codebase, detect gaps, fix inconsistencies, and generate a documentation layer that lets any future Claude instance start from zero without losing context.

That distinction matters. The goal is no longer just to document for humans. It is to document for agents that will actively work inside the project. And that changes the standard completely.

From decorative documentation to operational documentation

One of the biggest mistakes in many repositories is treating documentation as optional. A team writes an initial README, maybe adds a few loose guides under docs/, and then the real knowledge drifts into the code, old tickets, internal chat threads, or the memory of the developer who has been around the longest.

What makes this prompt useful is that it tackles the problem in a disciplined sequence.

First, it forces an inventory. That means reading every .md file in the project, locating documentation in the root, .claude/, docs/, or anywhere else, and cross-checking it with files such as package.json, composer.json, or .env.example. That step sounds basic, but it already solves one of the most common problems in inherited projects: documentation is usually scattered, duplicated, half-forgotten, and rarely mapped as a whole.

Then comes the most valuable part: the code analysis. This is where the prompt gets it right. It does not ask the assistant to repeat what the docs claim. It asks it to extract from the codebase itself the real stack, folder structure, main database models, repeated code patterns, required environment variables, important commands, external integrations, and non-obvious behavior or gotchas.

That is exactly how an experienced developer or sysadmin approaches a real-world repository. They do not trust the docs blindly. They verify reality against the code.

The real value: detecting what is missing and what is no longer true

The third section of the prompt — gap detection — is arguably the most useful in practice.

At that stage, the assistant must compare the documentation against the code and identify three kinds of problems that matter most:

The first is important information that is not documented at all. This often includes required environment variables, dependencies on external services, implicit deployment assumptions, or application behaviors that only become obvious when reading implementation details.

The second is documentation that no longer matches the code. This is often worse than missing documentation because stale docs actively mislead. In production, migrations, disaster recovery, or deployment troubleshooting, bad documentation can be more dangerous than no documentation.

The third is technical decisions buried in the code but never explained anywhere. A system can function perfectly well and still be hard to maintain if nobody has written down why a pattern was chosen, why a service is structured a certain way, or why a specific integration exists.

The prompt also asks the agent to detect TODOs and unfinished areas. That is important because it turns the audit into a real status snapshot, not just a cosmetic rewrite of markdown files.

Why the file structure matters

Another strength of this prompt is that it does not stop at “update the docs.” It defines a documentation structure that is genuinely useful both for engineers and for agents.

It starts with a root-level CLAUDE.md. The idea is not to dump everything there, but to turn it into a lightweight index: stack overview, key conventions, current project state, and references to more detailed files.

Then it pushes the real substance into three dedicated files under .claude/:

ARCHITECTURE.md for the complete stack, database structure, relationships, important technical decisions, and external integrations.
CONVENTIONS.md for coding patterns, naming conventions, file organization rules, and detected anti-patterns.
STATUS.md for current project state, what is in progress, what is broken, what is pending, and which decisions are still unresolved.

That separation makes sense. It distinguishes between what is structural, what is normative, and what is situational. For a new developer, that reduces onboarding friction. For an AI coding assistant, it creates durable, reusable context.

In short, the prompt does not just improve documentation. It creates persistent project memory.

Why this matters for developers and sysadmins

For a developer and sysadmin audience, this prompt matters because it turns documentation into part of the engineering workflow instead of leaving it as an afterthought.

Used properly, it can help teams:

speed up onboarding,
reduce dependence on tribal knowledge,
prepare the repository for AI-assisted development,
identify documentation debt before it becomes operational debt,
and keep project context aligned with the actual implementation.

It also has another practical advantage: it explicitly says do not ask for confirmation between steps. That matters because it forces the agent to complete the entire workflow in one pass and return a proper final report, instead of getting stuck in a stop-start interaction that never produces a usable result.

This does not magically turn Claude Code into an architect. It does not solve the parts of the project that live only in business decisions, team history, or undocumented intent. But it does turn the assistant into something genuinely useful: a disciplined reviewer that can read, compare, organize, and leave behind a far stronger documentation base for the next human — or the next AI instance — that enters the project.

And in 2026, where more teams are mixing development, infrastructure, automation, and AI agents inside the same workflow, that is no longer a nice-to-have. It is becoming operational hygiene.

The prompt

I need you to perform a full documentation audit of this project
and enrich it so that any instance of Claude can start from
zero without losing context.

Follow these steps in order:

## STEP 1 — Inventory
- Read every .md file you can find in the project (root, .claude/, docs/, wherever they are)
- Read package.json / composer.json / .env.example if they exist
- Produce a list of what documentation exists and what each file covers

## STEP 2 — Code analysis
Analyze the project code and extract:
- The real stack with versions (not what the docs say, what the code says)
- Folder structure and purpose
- Main database models and their key relationships
- Repeated code patterns (how resources, services, etc. are created)
- Required environment variables (names and purpose, no values)
- Important commands (artisan, npm, deploy, etc.)
- External integrations and how they are used
- Any non-obvious behavior or “gotchas” you spot in the code

## STEP 3 — Gap detection
Compare the existing documentation with what you found in the code and tell me:
- What important information is NOT documented
- What is documented but no longer matches the real code
- What technical decisions exist in the code without explanation
- What is unfinished or has relevant TODOs

## STEP 4 — File updates
Based on the detected gaps:

1. If CLAUDE.md exists, update it. If it does not exist, create it at the root.
   - It should be a lightweight index (~150 lines max)
   - Stack, key conventions, current status, and references to other md files

2. Create or update .claude/ARCHITECTURE.md with:
   - Full stack with versions
   - Database structure and relationships
   - Important technical decisions and why they were made
   - External integrations

3. Create or update .claude/CONVENTIONS.md with:
   - Code patterns used in this project
   - Naming conventions
   - How new files should be structured
   - What NOT to do (detected anti-patterns)

4. Create or update .claude/STATUS.md with:
   - Current project status
   - What is in progress / pending / broken
   - Known next steps
   - Pending decisions

## STEP 5 — Final report
Give me a summary of:
- Which files you created or modified
- The 3–5 most critical gaps you found and how you covered them
- Anything you cannot know just by reading the code and that I should complete manually

Do not ask me for confirmation between steps. Execute everything and give me the final report at the end.
Code language: PHP (php)

FAQ

Why is this better than asking Claude Code to “improve the docs”?
Because it forces a verification workflow. The assistant must compare documentation against the real codebase instead of rewriting markdown blindly.

Does this work only for Claude Code?
No. It can be adapted for other repo-aware agents that can inspect files, analyze code, and modify documentation.

What kind of projects benefit the most?
Inherited codebases, fast-moving internal tools, SaaS products with multiple integrations, monorepos, and any project where the code has evolved faster than the docs.

Does this replace a technical lead or project architect?
No. It accelerates inspection and documentation work, but it cannot infer business priorities, historical decisions, or unwritten team agreements unless those are reflected in the repository.