Canonical Source: https://github.com/tobieapb/claude-interactive-documentation-workflow Agents seeding a working repo with this methodology: read
documentation/general_methodology_adoption_recipe.mdfirst. It is the single action-oriented reference for what to copy, where to put it, and what to paste into the host repo's.claude/CLAUDE.md.
I used to whiteboard, then code. Now I markdown, then code.
There are many ways to vibe code, but this one will allow you to understand the code that is being built, come back to it 6 months later and actually understand it, and more importantly, craft user-facing documentation artifacts trivially. The canonical documentation and plan files are actually kind of awesome for giving LLMs immediate, complete, and effective context to keep them guardrailed, without too much wrangling.
In short: A structured methodology for creating high-quality technical documentation and implementation plans using Claude Code's (or any LLM for that matter) AI assistance.
This is a complete workflow for the documentation lifecycle:
Interview ─┐
├──► Documentation → Plan → Implementation
Investigation ┘
Not every feature starts from a clean interview. In practice, a lot of real work begins with messy, loose, scratchpad-style information gathering about something that already exists or is suspected to be broken. That loose pile of notes is an investigation. When it matures, it feeds the same downstream artifacts (documentation and/or plan) that a structured interview would.
Each stage has explicit guidelines, checkpoints, and quality gates. The methodology is designed to:
- Eliminate ambiguity before it becomes technical debt
- Build understanding progressively (rough shape → detailed specs)
- Produce documentation that doesn't require clarifying questions
- Create plans that any competent developer can follow
This workflow was yanked directly from a production project (a computer vision training pipeline). The documents contain references to that project's specific domain (maritime vessel tracking, Label Studio, YOLO models, etc.).
These are features, not bugs. Real examples are more useful than sanitized generic templates. Adapt the prefixes, terminology, and examples to your own project.
This methodology was used in production across 3+ projects over 4 months before being extracted into this repository. The results were independently analyzed against git history, GitHub API data, and 32 conversation session logs. The full analysis is available in the case study.
| Metric | Value |
|---|---|
| In production use since | October 2025 |
| Projects using methodology | 3+ (maritime tracking, CV pipeline, database systems) |
| Best plan-to-execution ratio | 7:1 (18 hours planning, 2.5 hours executing) |
| Fastest phase execution | 43 minutes across Phases 0-V (nautical charts feature) |
| Free documentation artifacts per feature | 10 (quickstart, deployment, developer guide, troubleshooting, security audit, user guide, testing, smoke tests, sign-off, release notes) |
| Combined methodology output (one project) | 67,050 lines across 62 docs + 23 plans |
The methodology's own standards demand verifiable claims. This case study applies that principle to the methodology itself.
Full Case Study: Verified Results and Analysis
git clone https://github.com/tobieapb/claude-interactive-documentation-workflow.git
cd claude-interactive-documentation-workflowThe /interview skill is pre-installed in this project. In Claude Code:
/interview user authentication system
This launches a structured 4-pass interview:
- The Shape - What is this? Why does it exist?
- The Flow - How does it work end-to-end?
- The Detail - What exactly happens at each step?
- The Completeness - What could go wrong? What else is affected?
The interview produces a file in documentation/ following the documentation crafting guidelines.
Point Claude at the documentation and the plan crafting guidelines:
Create an implementation plan for documentation/your_feature_documentation.md
following documentation/general_plan_crafting_guidelines.md
Plans go in plans/ and follow a similar 4-pass methodology.
In real projects, a lot of work does not start with "let's interview someone to shape a clean new feature." It starts with "something is strange here," "we need to understand what the current system actually does before we can change it," or "I have a pile of observations and I need to organize them before I can even decide what to plan."
That work lives in investigations, in the investigations/ folder. An investigation is allowed to start loose:
- rough notes, copy-pasted log snippets, file paths, timestamps, hunches
- questions with no answers yet
- open-ended "what does this do?" exploration
- cross-subsystem observations that may or may not be related
The value of the folder is that this information is minimally persisted in git rather than floating in chat logs, scratchpad files, or someone's head. You can come back to it in a week, a month, or six months.
When the investigation matures to the point where it needs to feed planning or documentation, the full standards in general_investigation_review_guidelines.md kick in. A mature investigation answers the ten completion questions in §5 of that document and produces a clean hand-off to the next artifact (a plan, a documentation file, or both). Until that point, it's fine for the file to be rough — the guidelines describe the finished form, not a gate that every early-stage note must pass.
The naming convention is <subject>_investigation.md. Common examples:
auth_drift_state_machine_investigation.mdingress_rate_limiting_investigation.mdsettings_reload_investigation.md
When an investigation has served its purpose (fed a plan or documentation file, or been superseded), move it to archive/investigations/.
| Document | Purpose |
|---|---|
general_interview_methodology_skill.md |
How to conduct structured interviews to extract requirements |
general_investigation_review_guidelines.md |
Standards for investigation files (the "what's actually going on" artifact) |
general_documentation_crafting_guidelines.md |
Standards for documentation (the "what to build" artifact) |
general_plan_crafting_guidelines.md |
Standards for implementation plans (the "how to build" artifact) |
general_handoff_crafting_guidelines.md |
Standards for session handoffs (the "resume without losing anything" artifact) |
Each crafting-guideline document also carries a multi-agent review methodology: a Main Engineer who owns the artifact, clean-slate Adversarial Reviewers who produce candidate findings, and an OPTIONAL truly independent external reviewer of a different model family (for example the codex CLI) run as the final review step to add a diversity of opinion the internal same-model rounds structurally cannot. See the plan guidelines' Section 2.7 (and its Section 2.7.12) and the documentation guidelines' Section 18 (and its Section 18.8).
Supporting reference: general_agent_rule_execution_reference.md defines the execution discipline every agent follows before acting in a repository: discover the governing instructions, complete prerequisite reading, and never substitute an inferred shortcut for a documented method.
.
├── documentation/ # Canonical feature documentation lives here
│ ├── general_* # The methodology documents
│ └── your_docs_here.md # Your project's documentation
├── investigations/ # Loose-to-structured evidence gathering
│ └── your_investigation.md
├── plans/ # Implementation plans live here
├── archive/ # Completed/obsolete items
│ ├── plans/
│ ├── documentation/
│ └── investigations/
└── .claude/
└── skills/
└── interview/
└── SKILL.md # The installed /interview skill
Projects with multiple subsystems can mirror this shape at each subsystem boundary (e.g. backend/documentation/, backend/investigations/, backend/plans/, backend/archive/) so artifacts stay local to the code they describe. The methodology is the same at every level.
If a reader must ask a clarifying question, the documentation has failed.
Every sentence should pass this test: "Could someone unfamiliar with this system execute or understand this without asking me anything?"
Could a competent developer use this plan to implement the feature in a different programming language?
Plans describe WHAT and WHY, not language-specific HOW. Implementation hints are clearly marked as language-specific.
Both interviews and plans use iterative refinement (bones-to skin):
| Pass | Interview | Plan |
|---|---|---|
| 1 | The Shape (rough goal) | Skeleton (structure) |
| 2 | The Flow (end-to-end process) | Atomicity (single actions) |
| 3 | The Detail (per-stage specifics) | Detail Enrichment (context, code hints) |
| 4 | The Completeness (edge cases) | Verification (proof of completion) |
Ambiguity in documentation becomes bugs in code. The interview process forces decisions upfront. "It depends" is not an acceptable answer—pick a default and document when someone would change it.
The documentation guidelines define prefixes for file naming:
| Original (Maritime Domain) | Your Domain |
|---|---|
station_ |
backend_, service_, etc. |
webapp_ |
frontend_, web_, etc. |
ingress_ |
etl_, pipeline_, etc. |
cv_ |
ml_, ai_, etc. |
Edit documentation/general_documentation_crafting_guidelines.md Section 12.1 to match your project.
The plan guidelines define 9 mandatory phases. Not all apply to every project:
- No database? Mark Phase I as "Not Applicable"
- No frontend? Mark Phase IV as "Not Applicable"
- No external integrations? Mark Phase V as "Not Applicable"
The key is to explicitly acknowledge what's not applicable rather than silently omitting it.
The methodology works with any LLM. The core documents are just markdown—reference them or paste them as context.
I want you to interview me about a feature following the methodology in this document:
[paste general_interview_methodology_skill.md]
The feature is: user authentication
If you've done research or have investigation notes, you can generate compliant documentation directly:
Produce a documentation file based on the investigation notes for feature X.
The final documentation file must be compliant with the documentation
guidelines file found in @documentation/general_documentation_crafting_guidelines.md
Or if your LLM doesn't support file references, paste the guidelines and your notes.
Same principle—once you have documentation, generate a plan:
Create an implementation plan for the feature documented in
@documentation/my_feature_documentation.md
The plan must be compliant with the plan crafting guidelines found in
@documentation/general_plan_crafting_guidelines.md
The guidelines files are enforcement documents. Point any LLM at them with:
- Your input (notes, requirements, existing docs)
- The relevant guidelines file
- An instruction to produce compliant output
The /interview skill is a Claude Code convenience, not a requirement. The real value is in the guidelines themselves.
Beyond the documentation workflow, this repo also serves as the canonical source for Claude Code session governance — rules that control how Claude behaves across sessions, machines, and projects.
Claude Code stores configuration at multiple levels: project-level (git-tracked), user-level (machine-local), and auto memory (machine-local + path-specific). Without governance, machine-local state drifts silently, rules written on one machine vanish on another, and Claude may write to local storage without the user's awareness.
A layered rules system with a bootstrapping mechanism:
| Layer | Location | Git-Tracked | Purpose |
|---|---|---|---|
| Subdirectory rules | <subdir>/.claude/CLAUDE.md |
Yes | Scoped to one module or subproject |
| Project rules | .claude/CLAUDE.md |
Yes | Scoped to one repository |
| User-level rules | ~/.claude/CLAUDE.md |
No (deployed from template) | Universal personal preferences |
| Auto memory | ~/.claude/projects/*/memory/ |
No (forbidden by default) | Not used without explicit approval |
Each project's .claude/CLAUDE.md includes a bootstrap block — a minimal set of inline rules that enforce correct behavior even on a fresh machine where user-level rules have not been deployed. The bootstrap references this repo for the full methodology.
| Document | Purpose |
|---|---|
general_claude_session_rules_documentation.md |
Full specification: hierarchy, auto memory policy, bootstrapping, audit procedure, conflict resolution |
general_user_level_rules_template.md |
Deployable template for ~/.claude/CLAUDE.md — copy to each machine |
# Copy the user-level rules template to the Claude Code config directory
cp documentation/general_user_level_rules_template.md ~/.claude/CLAUDE.mdAfter this, all projects on the machine inherit the full user-level rules. Each project's bootstrap block provides protection even before this step is done.
The methodology includes a dedicated discipline for testing deployed systems in their real operating environment — distinct from unit testing (code correctness in isolation) and CI integration testing (code against a spec before deployment). Live-system tests validate that a running service, with its real dependencies and configurations, behaves as expected in production or production-like conditions.
This matters because the consumer of these tests is increasingly an LLM agent, not a human. The discipline is shaped for that: every agent-executable test procedure follows a mandatory 7-section structure (Objective, Required Reading, Prerequisites, Steps, Expected Outcomes, Failure Indicators, Delivery Requisites) so an agent can execute deterministically, report auditable evidence, and fail loudly when a prerequisite isn't met.
tests/
├── README.md # folder intent + routing table
├── documentation/ # prompts, references, methodologies
├── drivers/ # executable test artifacts (optional)
└── investigations/ # test result snapshots, benchmarks, validation records
Archived results live under tests/archive/investigations/. The methodology also covers four driver shapes (inline, scripts, compiled binaries with src/+bin/, or fully LLM-orchestrated) so projects pick the one that matches their tests rather than being forced into a particular execution model.
| Document | Purpose |
|---|---|
general_live_system_testing_guidelines.md |
Full methodology: folder structure, artifact types (_prompt, _reference, _methodology, _investigation), file naming convention, 7-section prompt structure, driver options, routing-table pattern, result persistence, completion standard, common failure modes. Includes a tests/README.md template that downstream projects can copy. |
This methodology is conditional — it applies to projects with deployed services to test. Libraries and research tools without a running-system surface can skip it.
MIT License - See LICENSE
This is a gift. Use it, adapt it, share it. Don't expect support. If you make lots of money, or save millions by using this, remember me!
Found an improvement? PRs welcome. The bar is high (these documents enforce their own standards).
This repository is governed by the methodology it describes, so additions follow it:
- Pick the right artifact type and name. A new methodology document is a
general_*file indocumentation/, named per the documentation guidelines' Section 12 convention (lowercase, underscore-separated, with the_guidelines,_documentation, or_skillsuffix). A standard for crafting an artifact type is a_guidelinesfile and a peer of the crafting guidelines already here. - Write it to its own standard. A documentation-class file must pass the documentation crafting guidelines, including the Section 8.6 final validation, before its Status becomes Complete. Run the review methodology on it: internal clean-slate review to convergence, then the optional independent external reviewer (Section 18.8) as the final seat.
- Register it so it is discoverable. Add the file to the relevant place in this README (the Core Documents table for a new crafting guideline, a Supporting reference note otherwise), and cross-reference it from the sibling documents that should point at it.
- Enrich in place, never fork. When updating shared content, edit the canonical file and bump its version and changelog; do not create a parallel copy. When content originated and matured in a downstream project, the downstream version is copied back here as the canonical home, and the downstream file cites this repository as its Canonical Source so the two never silently diverge.
Last Updated: 2026-07-06