Improve your documentation with the Chunk AI agent

Documentation is one of those things everyone agrees is important until it’s time to actually write it. Code changes ship, features evolve, and documentation falls out of sync. New team members struggle to understand how things work, and even experienced developers waste time reverse-engineering code that should have been documented months ago.

The challenge has intensified with AI-assisted development. When AI coding assistants can generate features in minutes, documentation falls even further behind. The code that took hours to write manually might have warranted careful documentation. Code generated in seconds often ships without any. The result is a growing gap between what your codebase does and what anyone can understand about it.

Chunk, CircleCI’s autonomous CI/CD agent, addresses this by bringing AI-powered documentation generation directly into your continuous integration pipeline. Unlike IDE-based tools that work on individual files, Chunk can analyze your entire codebase, understand how modules interact, and generate comprehensive documentation that reflects the actual implementation. In this guide, you’ll learn how to use Chunk to improve documentation automatically.

Setting up Chunk

To get started with Chunk, you’ll need a CircleCI account with a project already running pipelines. If you’re new to CircleCI, check out the getting started guide to connect your repository.

You can follow along with your own project or use our demo project on GitHub if you’d like a ready-made example.

Once your project is running in CircleCI:

1. Go to Chunk in the CircleCI web app sidebar.
2. Click Set up Chunk and follow the prompts to authorize GitHub access. Chunk requires read access to analyze your repository and write access to create pull requests with its documentation updates.
3. Connect your Anthropic or OpenAI API key when prompted. Chunk uses your own API credentials, so your code is never sent to external providers for model training and data stays under your control.

Chunk integrates directly with your existing CircleCI pipelines without requiring any reconfiguration. Once authorized, it can analyze both your repository code and your build history to understand how your project works. For complete setup instructions, see the Chunk documentation.

Asking Chunk to improve documentation

With Chunk enabled, select Chunk from the sidebar. You’ll see a prompt interface where you can describe what you want Chunk to do.

Start with a simple prompt:

Improve documentation

Click Submit and Chunk begins working. Because Chunk operates within your CI/CD environment, it can analyze your entire codebase to understand module relationships, function signatures, and usage patterns. It uses this comprehensive view to generate documentation that accurately reflects how your code actually works.

Reviewing the results

When Chunk completes its analysis, you’ll see a summary of the documentation it generated. From this page, you can review the details and decide whether to open a pull request. If you’re not satisfied with the changes, you can skip the PR and refine your prompt instead.

Chunk explains its changes:

Summary
Expanded the README with complete API documentation covering all
validators, transformers, processors, and exporters. Added detailed
function signatures, parameters, return types, and usage examples
for each module.

Changes
Enhanced project description with feature highlights

Added comprehensive API Reference section with:
- Validators: validateEmail, validatePhone, validateDate, validateCurrency
- Transformers: csvToJson, normalizeData
- Processors: processBatch, createPipeline
- Exporters: exportToJson, exportToJsonLines, parseJsonSafely

Included detailed examples and expected outputs for each function

Added development and testing sections with new commands

Replaced basic usage section with detailed API reference documentation

If the changes look good, click Open Pull Request to create a PR in your repository.

Before merging, review the generated documentation to ensure it accurately describes how the code works. Chunk analyzes the implementation to generate documentation, but you should verify the descriptions match your intended design.

More targeted prompts

The simple “Improve documentation” prompt works well for general documentation gaps. For more control over what Chunk documents, try targeted prompts.

To document a specific module, run:

Add JSDoc comments to all functions in src/validators

To update the README, run:

Update the README with installation instructions and usage examples

To document complex logic, run:

Add inline comments explaining the pipeline execution flow in
src/processors/pipeline.js

To generate API documentation, run:

Create API documentation for all exported functions with parameter
types and return values

To document for a specific audience, run:

Add documentation to the transformers module aimed at developers
who are new to the codebase

The more specific you make your prompt, the more focused Chunk’s documentation will be.

Advanced configuration

Once you’re comfortable with the basics, you can fine-tune how Chunk operates with your project.

Environment setup

For projects with complex dependencies or build processes, you can provide a .circleci/cci-agent-setup.yml file that tells Chunk exactly how to prepare your environment.

While documentation generation doesn’t always require running tests, Chunk may need to build your project to understand type information, module exports, or generated code. Common use cases include:

• TypeScript projects: Build step to generate type definitions
• Generated code: If documentation depends on code generation (API clients, GraphQL types)
• Monorepos: Setup for navigating multiple packages
• Custom build tools: If your project uses non-standard build processes

Here’s an example for a TypeScript project:

version: 2.1

workflows:
  main:
    jobs:
      - cci-agent-setup

jobs:
  cci-agent-setup:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run:
          name: Install Dependencies
          command: npm ci
      - run:
          name: Build TypeScript
          command: npm run build

Focus on environment preparation only. Chunk will determine how to analyze your code based on your project structure.

Chunk will attempt to automatically create this file if needed. You can also manually generate one. Go to Organization Settings -> Chunk Tasks. Click the menu (…) for your task. Click Chunk Environment, then click Create File in GitHub. For more details, see the Chunk environment documentation.

Custom instructions

To ensure generated documentation matches your team’s standards, create a claude.md or agents.md file in your repository root. Document your preferences for:

• Documentation format (JSDoc, TSDoc, docstrings, etc.)
• Level of detail for different types of code
• Whether to include usage examples
• Tone and style (formal, conversational, etc.)
• Languages for multilingual documentation

Chunk reads these files and applies your preferences when generating documentation.

Documentation consistency

Chunk can maintain documentation consistency across your codebase by following patterns it finds in existing documentation. If some modules are well-documented, Chunk uses those as templates for documenting similar modules. This helps maintain a consistent voice and format throughout your project, which is especially valuable when different team members have contributed documentation over time.

Chunk in the AI development ecosystem

While AI coding assistants help you write code faster in your IDE, documentation often gets left behind. Chunk operates at the CI/CD layer where it can analyze your complete codebase and generate documentation that reflects the actual implementation.

This positioning creates a natural checkpoint in AI-assisted workflows. Code generated by AI assistants ships through CI/CD, where Chunk can ensure it’s properly documented before it accumulates into an undocumented mess. Rather than relying on developers to remember to document AI-generated code, Chunk can handle it automatically.

For teams using AI coding assistants, CircleCI also offers the CircleCI MCP Server, which connects AI assistants directly to your pipelines using the Model Context Protocol. This creates tighter integration between your IDE-based AI tools and your CI/CD infrastructure. Together, Chunk and the MCP server create an integrated AI development workflow where code quality, testing, and documentation are all maintained automatically.

Conclusion

Outdated or missing documentation doesn’t have to slow your team down. Chunk analyzes your codebase, identifies documentation gaps, and generates clear, accurate documentation that helps everyone understand how things work. As AI-powered development accelerates the pace of code changes, having an autonomous agent that keeps documentation current becomes essential for team productivity.

Ready to try it yourself? Sign up for a free CircleCI account and enable Chunk to start improving documentation automatically.