Documenting COBOL code with AI: a practical guide (2026)

There are 220 billion lines of COBOL running banking, government, and healthcare systems right now. The developers who wrote most of it are retiring at a rate of about 10% per year, and over 60% are expected to be gone within five years. The documentation situation on most of those systems ranges from sparse to nonexistent.

AI doesn’t solve this problem completely. But used correctly, it makes the documentation effort significantly more tractable. This guide covers what works, what doesn’t, and how to build a repeatable workflow for documenting COBOL programs with AI.

What AI can and can’t do with COBOL (be honest about this)

Before diving into prompt templates, the honest picture on AI limits for COBOL matters.

Swimm benchmarked Claude Code (Opus 4.6) against real Medicare COBOL programs from CMS archives. On a smaller 4,692-line program, Claude covered 69-86% of paragraphs across three runs. On a larger 18,835-line program, coverage dropped to 24-35%, with results varying by up to 42% between identical runs on the same code. Claude completely missed a 70-line payment calculation subsystem across all three attempts.

That sounds bad. Here’s the reframe: those benchmarks tested one-shot full-program extraction, where AI is asked to extract every business rule from a large program in a single prompt. That’s the wrong use case for documentation.

The chunked workflow changes the math entirely. When you feed AI a single COBOL section or procedure, give it explicit context about the platform and business domain, and review the output before moving on, the accuracy is much higher and the errors are more catchable. The Swimm result is a warning against one-shot extraction. It isn’t a verdict against AI for guided documentation.

One firm rule: AI is most reliable when reading and explaining code, not generating it. Use it for explanation, not for writing new COBOL based on its interpretation.

Tools that work for COBOL documentation

Claude (claude.ai or API): Accessible, produces structured explanations, and handles COBOL reasonably well when given context. Hit the chunk-size limit on programs over roughly 500-800 lines per prompt. The API version lets you process chunks programmatically if you want to build a documentation pipeline.

ChatGPT / GPT-4o: Solid COBOL familiarity given the volume of mainframe documentation in its training data. Similar chunk-size constraints. The choice between Claude and ChatGPT for COBOL is largely personal preference; both are workable with the right prompts.

IBM watsonx Code Assistant for Z: The purpose-built option. It integrates directly into VS Code, is designed specifically for z/OS COBOL, and handles the full understanding-to-modernization workflow. General watsonx Code Assistant pricing starts around $2 per 20 task prompts on a consumption model, but the Z-specific variant uses an enterprise contract model. Contact IBM for pricing. Worth evaluating if your shop has an existing IBM relationship and a dedicated mainframe team.

DocuWriter.ai and Kodesage: Both offer COBOL-specific documentation features with on-prem or VPC deployment options. Kodesage also supports Oracle Forms, PowerBuilder, and SAP. These are useful for shops that need to run documentation tooling on-premise for compliance reasons or don’t want to send code to a third-party API.

Prompt templates that work

Give AI explicit context before showing it code. Generic prompts produce generic output. Mainframe-specific prompts that identify the language, compiler, platform, and program purpose produce documentation you can actually use.

Template 1: Program-level summary

You are reviewing a COBOL program running on IBM z/OS using VSAM files. The program is part of [describe the business system, e.g., "a batch payroll processing system"].

Review the following COBOL source code and produce:
1. A program summary (3-5 sentences): what the program does, what files it reads/writes, and what its role is in the larger system
2. A list of called subprograms, if any
3. A high-level data flow: what input triggers the program, what it processes, and what output it produces

Code:
[paste IDENTIFICATION DIVISION and first 100-150 lines, or the full program if under 500 lines]

Template 2: Section or paragraph documentation

This is a section from a COBOL program that handles [describe context, e.g., "benefit deduction calculations for a payroll batch job"] on IBM z/OS.

For each paragraph in the following code, write a plain-English explanation of what it does. Be specific about what data it reads, what logic it applies, and what it outputs or modifies. Flag any regulatory constants or hardcoded values that look like they may need verification.

Code:
[paste one section, typically 50-150 lines]

Template 3: Business rule extraction from a single paragraph

This COBOL paragraph is part of a [describe system]. Extract the business rules it implements as a numbered list. Each rule should be a plain-English statement of what the logic enforces. Do not generate new code. If a constant appears to encode a regulatory value (a rate, a threshold, a date), flag it for human review.

Code:
[paste single paragraph]

Template 4: REMARKS block generation

Based on the following COBOL program source, write a REMARKS block for the IDENTIFICATION DIVISION. Include: program purpose (2-3 sentences), input files, output files, called programs, and a change history entry for today's date noting that initial documentation was added.

Code:
[paste the program]

A realistic workflow for a 5,000-line COBOL program

Here’s how to apply this in practice.

Step 1: Program-level pass. Run Template 1 on the full program if it’s under 500 lines, or on the IDENTIFICATION DIVISION, FILE SECTION, and WORKING-STORAGE SECTION if it’s longer. The goal is a plain-English program summary and a map of what the program connects to. Takes 10 minutes.

Step 2: Chunk by section. Divide the PROCEDURE DIVISION into logical chunks, typically one major section at a time. Run Template 2 on each chunk. For a 5,000-line program this is usually 8-15 chunks. Each chunk takes 5-10 minutes to run and review.

Step 3: Human review of each chunk. Have a developer with COBOL experience read the AI output against the code. Flag inaccuracies, fill in business context AI can’t know from the code alone, and verify any constants or thresholds that look like they encode business rules. This review step is what makes the output trustworthy.

Step 4: Assemble and write the REMARKS block. Combine the program summary from Step 1 with the paragraph-level documentation from Steps 2 and 3. Use Template 4 to generate a REMARKS block, then review and correct it. Add inline comments to the most complex paragraphs.

Total time for a 5,000-line program: 4-6 hours including human review. That’s significantly faster than writing documentation from scratch, and the output is consistent enough to be useful for onboarding and audit purposes.

What to avoid

Don’t run a single prompt on a large program. The Swimm benchmarks showed 24-35% coverage on 18,000-line programs. You’ll miss material paragraphs and won’t know which ones.

Don’t trust AI on regulatory constants without checking. Hardcoded rates, thresholds, and date constants in COBOL programs often encode regulations that change. AI will explain what the constant does but can’t tell you if the value is still current.

Don’t skip human review for production-critical logic. AI documentation is a first draft, not a finished product. Paragraphs that handle money, compliance rules, or file destruction need a human set of eyes on the explanation before you rely on it.

Don’t use AI to generate new COBOL based on its documentation output. The documentation workflow is reliable for explanation. Using that explanation as a basis for AI-generated COBOL introduces the risk of errors compounding. Keep the use case focused on reading and explaining, not generating.

Documentation first, then modernization

Documentation is the prerequisite for every downstream effort: refactoring, migration, onboarding, and knowledge transfer. It’s especially urgent in mainframe environments where the average COBOL developer is 55 years old and the knowledge walking out the door each year is not being written down.

The workflow in this guide is a practical starting point. It won’t give you perfect documentation in one pass. It will give you a documented foundation that a developer can verify and extend, which is substantially better than no documentation at all.

The same approach works for RPG IV on IBM i. If you’re dealing with both environments, see Documenting RPG IV code with AI: a practical guide for IBM i developers for IBM i-specific prompts and context.

For the full IBM i modernization picture, including how documentation fits into a larger modernization project, the IBM i AI Field Guide covers 35 IBM i-specific prompts and workflow templates.

Frequently asked questions

Can AI fully document a large COBOL program automatically?

No, not reliably. Benchmarks show Claude covers 24-86% of paragraphs on large programs, with results varying up to 42% between identical runs. The chunk-and-review workflow in this guide, documenting section by section with human review at each step, is far more accurate than asking AI to process a 10,000-line program in one shot.

Does Claude or ChatGPT work better for COBOL documentation?

Both work. ChatGPT has more COBOL in its training data than RPG IV, so baseline familiarity is solid. Claude tends to produce more structured explanations. Either way, you’ll get better results by giving explicit context in the prompt: language, platform, compiler, and what the program connects to.

Is IBM watsonx Code Assistant for Z worth it?

For large shops with dedicated mainframe teams and existing IBM contracts, it’s the most purpose-built option available. For smaller teams or shops without an enterprise IBM relationship, the combination of Claude or ChatGPT plus the workflow in this guide is a practical starting point at a fraction of the cost.

How long does documenting a COBOL program with AI actually take?

A 5,000-line program using the chunked workflow takes roughly 4-6 hours including human review. That’s significantly faster than documenting from scratch, and the output is more consistent. The time investment scales with program complexity, not just line count.

Does this approach work for RPG IV too?

Yes. The same chunked workflow applies to RPG IV. See the companion article on documenting RPG IV code with AI for IBM i-specific prompt templates and context.