RFC: Codebase Documentor Plugin

[XinyuQu]

Is this related to an existing feature request or issue?

No

Summary

This RFC proposes a new codebase-documentor plugin that analyzes application code and infrastructure-as-code to generate structured technical documentation, architecture diagrams, and optionally business documentation — with full source-of-truth citations linking every finding back to the specific code that produced it. The plugin addresses two growing problems: tribal knowledge loss when engineers leave teams, and the documentation gap created by AI-assisted coding where thousands of lines are generated faster than teams can document them. The plugin is general-purpose for any codebase but includes AWS-specific skills for understanding CDK, CloudFormation, and enriching documentation with AWS service context.

Use case

Target users: Teams inheriting legacy or abandoned codebases where original authors are unavailable, teams working with AI-generated code that lacks design context, engineers onboarding onto undocumented services, and tech leads managing services where tribal knowledge has been lost.

Motivation:

Two forces are making this problem worse:

1. Tribal knowledge decay — Engineers rotate teams or leave organizations. Services that were well-understood become black boxes. Design decisions, business context, and operational knowledge exist only in the heads of people who are no longer available. Teams spend days or weeks reverse-engineering code that someone once understood completely.

2. AI-assisted coding velocity — AI coding tools let developers produce thousands of lines of code in hours. The code works, but nobody — including the developer — has documented why it's structured this way, what business problem it solves, or how the pieces fit together. Without this plugin, coding agents perform ad-hoc discovery every time with no defined instructions for analyzing AWS-specific infrastructure, no consistent documentation format, and no structured output. The gap between code production speed and documentation speed is widening.

A critical gap in both scenarios is traceability. Even when someone manually writes documentation for undocumented code, there's no way to verify where each claim came from. Over time, documentation drifts from code and becomes unreliable. This plugin addresses that by embedding source-of-truth citations — every finding in the generated documentation links back to the specific file and line that produced it, making the documentation verifiable and maintainable.

Key use cases:

• Undocumented service discovery: A team inherits a service with zero documentation. The plugin reads the codebase and produces structured technical and business docs with citations to the exact code that each finding was derived from.
• AI-generated code explanation: A developer used AI to scaffold a service. The plugin captures the architecture, design decisions, and business logic into traceable documentation before context is lost.
• New team member onboarding: Instead of spending weeks reading code, a new engineer gets generated documentation as a starting point — and can follow citations to verify and deepen their understanding.
• Post-incident understanding: After an incident in an unfamiliar service, the plugin quickly produces a technical overview so responders understand what they're looking at, with direct links to the relevant code.

Proposal

User experience

Before (without the plugin):

User:  I need to understand the order-processing service.
       The team that built it left 6 months ago.

Agent: I can see there's an order-processing directory with some
       Lambda functions and a DynamoDB table. Would you like me
       to look at specific files?

[User spends hours manually reading files, tracing code paths,
 and piecing together how the service works]

Or, with AI coding agents:

User:  Help me understand the order-processing service.

Agent: [Reads random files, gives a surface-level summary]
       This appears to be a Node.js service with some Lambda
       functions. There's a DynamoDB table and some SQS queues.

[Every time someone asks, the agent re-discovers from scratch.
 No consistent format. No AWS-specific infrastructure analysis.
 No architecture diagram. No reusable documentation artifact.
 No way to verify where any claim came from.]

After (with codebase-documentor):

User:  Generate documentation for the order-processing service.

Agent: I'll analyze the order-processing service and generate
       documentation. Do you have any existing docs, design
       documents, or context you can share before I start?

User:  Nothing. The team that built it left months ago.

Agent: Understood. Analyzing codebase...

       Scanning: source code, IaC, configs, tests, README files...

       Generated artifacts:

       1. TECHNICAL.md
          - Architecture overview: Event-driven, 4 Lambda
            functions, 1 DynamoDB table, 2 SQS queues, 1 SNS topic
          - Code analysis: Module structure, key code paths,
            entry points, internal dependencies
          - API contracts: 3 REST endpoints documented
          - Data models: Order, OrderItem, PaymentRecord
          - Deployment: CDK TypeScript, single-stack,
            deployed to us-east-1
          - Failure modes: DLQ configured on order-queue,
            no retry on payment-gateway timeout [RISK]
          - Auto-generated API documentation (if OpenAPI/Swagger
            specs detected)

          Every finding includes source citations:
            "Event-driven architecture using SQS → Lambda"
            ← lib/order-stack.ts:45-52 (queue-to-Lambda binding)
            ← src/handlers/process-order.ts:12 (SQS event handler)

       2. Architecture diagram
          - Application component relationships from code analysis
          - AWS service topology from CDK stack analysis
          - Data flow between components

       3. BUSINESS.md (optional, if sufficient context available)
          - Service purpose, business capabilities, data flows,
            upstream/downstream dependencies

       ⚠ Items marked [UNKNOWN] — could not be inferred from code:
       - SLA requirements for order completion
       - On-call team for DLQ alarm monitoring
       - Business reason for 30-day order retention policy

Plugin structure

plugins/codebase-documentor/
├── .claude-plugin/
│   └── plugin.json
├── .mcp.json
└── skills/
    ├── document-service/
    │   ├── SKILL.md                       # ~150 lines, main workflow
    │   └── references/
    │       ├── technical-doc-template.md      # Sections, structure, examples
    │       ├── business-doc-template.md       # Sections, structure, examples
    │       ├── discovery-patterns.md          # How to extract info from code
    │       └── framework-patterns.md          # Common framework conventions
    └── draw-architecture/
        ├── SKILL.md                       # ~100 lines, diagram generation
        └── references/
            └── (to be determined — reference file strategy
                 for this skill is under discussion)

Skills

Skill 1: document-service

Purpose: Read a codebase or service directory and generate structured technical documentation with source-of-truth citations, with optional business documentation.

Trigger intents: "generate documentation for this service", "generate docs for this codebase", "create technical docs for this project", "document this service for me"

Note: This skill should only trigger on explicit documentation generation requests. It should not trigger during regular coding workflows, code reviews, or general questions about code.

Workflow:

1. Ask user if they have any existing documentation or context to share
2. Discover — scan source code, IaC, configs, tests, READMEs, package manifests
3. Generate technical documentation (TECHNICAL.md) as the primary output, with source citations for every finding
4. Generate business documentation (BUSINESS.md) as an optional output when sufficient business context is available
5. Mark items that cannot be inferred from code as [UNKNOWN]

Source-of-truth citations: Every claim in the generated documentation must include a citation pointing to the specific file(s) and line number(s) from which the finding was derived. This makes the documentation verifiable — a reader can follow any citation to confirm or update the finding. It also makes documentation maintenance practical: when cited code changes, the corresponding documentation is clearly identifiable as potentially stale.

Citation format is to be discussed, but an example:

## Architecture Overview

The service uses an event-driven architecture with SQS queues
triggering Lambda handlers for asynchronous order processing.

> Sources:
> - `lib/order-stack.ts:45-52` — SQS queue to Lambda event source mapping
> - `src/handlers/process-order.ts:12-18` — SQS event handler entry point
> - `src/handlers/charge-payment.ts:8` — SNS trigger for payment processing

Output — the primary artifact is the technical document. The business document is optional because business context is difficult to derive from code alone and may require additional human input. Output format for both documents is to be discussed.

TECHNICAL.md sections:

Section	Description
Architecture overview	High-level architecture and design patterns used, with citations
Code analysis	Module structure, key code paths, entry points, internal dependencies, with citations
Components	Services, functions, databases, queues, and their roles, with citations
API contracts	Endpoints, request/response schemas, authentication (including auto-generated API docs from OpenAPI/Swagger if detected), with citations
Data models	Core entities, schemas, relationships, with citations
Deployment	IaC stack description, regions, environments, with citations
Configuration	Environment variables, feature flags, secrets references, with citations
Failure modes	Error handling, DLQs, retries, circuit breakers, known risks, with citations
Runbook hints	Deployment steps, rollback procedures (if inferable from scripts/CI), with citations

BUSINESS.md sections (optional):

Section	Description
Service overview	One-paragraph purpose and business function
Business capabilities	What the service does in business terms
Data flows	Key business processes and data movement
Dependencies	Upstream and downstream service dependencies
SLAs and constraints	Performance/availability requirements (if documented in code/config)

Skill 2: draw-architecture

Purpose: Generate an architecture diagram showing service topology, data flows, and component relationships. When IaC is available, the diagram includes AWS resource topology. When no IaC is present, the diagram is generated from code analysis — the agent infers architecture from application code structure, imports, API calls, database connections, and message queue patterns to produce the best possible representation of the system.

Trigger intents: "draw the architecture", "architecture diagram", "visualize this infrastructure", "show me the architecture of this service", "diagram this stack"

The diagram always includes two layers:

1. Code-level architecture (always present): Application components, modules, internal dependencies, data flow between components — inferred from code analysis
2. Infrastructure-level architecture (when IaC available): AWS service topology, resource relationships, networking — parsed from CDK/CloudFormation/Terraform

IaC support (read-only — no modifications):

• CDK TypeScript
• CloudFormation YAML/JSON
• Terraform HCL

Diagram output format: To be discussed. Candidates include Mermaid (text-based, renders in GitHub), Draw.io XML, PDF with AWS architecture icons, or a combination. The preferred approach should balance portability, visual clarity, and the ability to represent AWS service relationships. Community input welcome.

Reference file strategy for this skill is under discussion. The approach to diagram conventions, AWS service icon mappings, and IaC parsing guidance will be determined as the diagram output format is finalized.

MCP server dependencies

Server	Type	Purpose	Required?
awslabs.aws-documentation-mcp-server	stdio	Enrich generated docs with AWS service descriptions, link to official documentation, reference Well-Architected guidance	When AWS services detected
awslabs.aws-iac-mcp-server	stdio	Parse CDK/CloudFormation resource schemas for accurate architecture diagram generation	When CDK/CFn detected

Additional MCP dependencies — particularly for diagram generation tooling — are subject to further discussion as the plugin design evolves.

Skill design

Both skills follow progressive disclosure:

• SKILL.md (loaded on trigger): Workflow steps, output format summary, defaults, quick-start examples. ~150 lines for document-service, ~100 lines for draw-architecture.
• Reference files (loaded on demand): Full doc templates, framework-specific discovery patterns. Loaded only when the agent needs them during execution.

Defaults

Setting	Default	Rationale
Output format	To be discussed	See open questions on document and diagram format
Primary output	Technical documentation with source citations	Most reliably derived from code; always generated; citations make findings verifiable
Business documentation	Optional	Requires business context that may not exist in code; generated when sufficient signals are present
Scope	Single service/directory per invocation	Ensures focused, high-quality output for each service
IaC reading	Read-only	Plugin never modifies infrastructure code
Diagram format	To be discussed	See open questions on diagram tooling
AWS enrichment	Enabled when AWS services detected	Adds AWS doc links and service descriptions automatically
Unknown markers	[UNKNOWN] inline tags	Clearly signals what couldn't be inferred from code
Code analysis	Always included	Architecture is always inferred from code; IaC analysis supplements but does not replace code analysis
Source citations	Always included in technical documentation	Every finding links to the file and line it was derived from

Out of scope

• Code review or quality assessment — the plugin documents what exists, it does not evaluate whether the code is good or suggest improvements
• Code modification — all analysis is read-only; the plugin never writes to source code or IaC files
• Deployment or infrastructure changes — no overlap with deploy-on-aws; this plugin reads IaC to understand architecture, not to deploy or modify it
• Monitoring or observability — no overlap with aws-observability; this plugin does not query CloudWatch, logs, or metrics
• Auto-triggering or continuous documentation — v1 is on-demand only, triggered by explicit user request; no hooks that fire on code changes or CI events
• Wiki or Confluence integration — to be discussed; v1 targets local file output, but integration with external documentation platforms may be considered in future iterations
• Multi-repository analysis — scoped to a single repository per invocation

Potential challenges

Challenge	Mitigation
No IaC found in codebase	Agent infers architecture entirely from code analysis — application structure, imports, API calls, database connections, message queue patterns. The diagram represents the best understanding from available code. Infrastructure-level details are marked [UNKNOWN] where they cannot be determined.
Unrecognized framework or language	Fall back to generic code analysis (function signatures, imports, API routes, directory structure); flag sections with lower confidence
Conflicting signals in code	Mark conflicting findings explicitly (e.g., "README says X but code does Y") with citations to both sources, rather than guessing which is correct
Stale README or existing docs	When existing docs are found, the plugin notes discrepancies between docs and code with citations to the conflicting sources
Trigger specificity	Skill description must be narrow enough to trigger only on explicit documentation generation requests, not during regular coding, code review, or general code questions
Citation accuracy	Citations must point to actual file paths and line numbers in the analyzed codebase; the agent must verify citations are accurate before including them

Dependencies and Integrations

• awslabs.aws-documentation-mcp-server — for AWS service documentation enrichment
• awslabs.aws-iac-mcp-server — for CDK/CloudFormation schema parsing
• Potential diagramming tooling dependency — to be determined based on diagram format decision

This plugin complements deploy-on-aws (which generates infrastructure) by documenting existing infrastructure. It complements aws-observability (which queries runtime data) by documenting static code and architecture.

Alternative solutions

• Manual documentation sprints — teams periodically dedicate time to write docs. Works in theory, rarely happens in practice, and doesn't scale with AI-assisted coding velocity.
• Simply asking the AI agent to "explain this code" — produces a one-time chat response, not structured, versioned documentation artifacts. No templates, no consistency across services, no architecture diagrams, no source citations. Every person who asks gets a different answer with no way to verify claims.

[scottschreckengaust]

Suggestion for "document this code" as a triggering statement.

[krokoko]

Thanks @XinyuQu ! That is a great idea ! Quick questions/notes:

1. Maybe I'm wrong but the way I read it this is a general purpose plugin for code understanding, and this marketplace is positioned around AWS capabilities, we might update the description to make the plugin specifically about documenting AWS-deployed services and their infrastructure.
2. The document-service seems to focus on many things, might need to break it down into separate skills (we'll see during implementation)
3. How are you planning on verifying confidence in the provided citations ? I think this is very important, if citations are unreliable, the value prop collapses
4. What about idempotency? If a user runs the plugin twice on the same codebase, what happens? The output should be deterministic enough that re-running produces a consistent result (modulo code changes)
5. We probably need to document limitations of this plugin for a first version. I'm thinking large, legacy codebases, and how this kind of use case requires multiple approaches

[XinyuQu]

Thank you @krokoko .

1. Maybe I'm wrong but the way I read it this is a general purpose plugin for code understanding, and this marketplace is positioned around AWS capabilities, we might update the description to make the plugin specifically about documenting AWS-deployed services and their infrastructure.

Yes I agree. During implementation, I will update the description & instructions to be more crafted towards AWS related services; at the same time, this plugin will be extensible enough to cover general codebase analysis

2. The document-service seems to focus on many things, might need to break it down into separate skills (we'll see during implementation)

Good points. I will try if I can break document service into smaller modules.

3. How are you planning on verifying confidence in the provided citations ? I think this is very important, if citations are unreliable, the value prop collapses

Very good point and the answer is to be decided. I will research this during implementation. Not only for the citation, but we will also need to find a way to figure out how effectively this plugin can analyze the document.

4. What about idempotency? If a user runs the plugin twice on the same codebase, what happens? The output should be deterministic enough that re-running produces a consistent result (modulo code changes)

Same as answer above. Eval method for this plugin is not clear yet. Open to all the suggestion.

5. We probably need to document limitations of this plugin for a first version. I'm thinking large, legacy codebases, and how this kind of use case requires multiple approaches

Agree on we need to have limitations on first version. Similar to answer 3 & 4, we need to build one / multiple test dataset to evaluate this plugin, and then limitation will be clear with testing results.

[krokoko]

Great, go for it!