Creating Onboarding Documentation with AI

1. Why onboarding documentation in Magento projects goes stale fast

Onboarding documentation in Magento projects is almost always written at the start of a project, when the structure is still small and easy to describe, and then rarely touched again, even though modules, conventions and deploy processes keep changing. For new developers this means the existing documentation describes a state that no longer matches the actual repository, and the only reliable source becomes asking experienced colleagues directly. That ties up senior time, slows down the productive start, and means every new hire effectively starts from zero instead of building on prior work.

This is especially error prone in projects with a dual vendor workflow, custom ViewModels instead of Block classes, and a fixed deploy sequence with several steps that must run in order: a single skipped step during static content deployment can trigger hours of debugging that an up to date guide would have prevented. This is exactly where AI can help, not as a replacement for team knowledge, but as a tool that speeds up the first, most tedious step of taking stock of the codebase.

2. Capturing the codebase and conventions with Claude

Claude Code can explore a repository on its own, without every file having to be copied into a chat manually. For taking stock of a codebase that means a single request is enough to extract directory structure, module names, namespace conventions and recurring patterns such as using ViewModels instead of Block classes. The decisive difference from a manual survey is not accuracy but speed: what a new developer painstakingly pieces together over the first two weeks, Claude delivers in structured form within minutes as a starting point.

What matters is keeping the request narrow and asking for concrete, verifiable artifacts, such as a list of every module with its dependencies pulled from the respective module.xml files, the design patterns actually used from etc/di.xml, or the CLI commands actually referenced in the bin/ directory. An open ended question like "describe the architecture" leads to vague, hard to verify results, while a precise request for verifiable facts from the code produces a draft that can be checked point by point.

#!/usr/bin/env bash
# Ask Claude Code to scan the repository and extract verifiable facts
# for a first onboarding draft, instead of guessing from memory

cd src

claude -p "Scan app/code, app/design/frontend and the etc/ directories.
List every custom module with its namespace, its dependencies from
module.xml, and the design patterns actually used (ViewModel vs Block,
Plugin vs Preference). Also list every wrapper command in bin/ with a
one-line description derived from the script itself.
Mark every claim you cannot verify from the files with 'TODO: verify'." \
  --allowedTools "Read,Grep,Glob" \
  > docs/onboarding-context.md

echo "Draft context written to docs/onboarding-context.md, review before use"

3. From repository to onboarding guide: structure and a first draft

The initial survey can be turned into a structured onboarding guide with fixed sections such as project overview, local setup, architecture basics, coding conventions and common pitfalls. Claude can fill this structure directly with content derived from the code, for example the Docker Compose configuration for the local setup section or the PHPStan rules for the coding conventions section. The generated draft is deliberately not the finished documentation, it is a skeleton of solid, code derived facts with clearly flagged gaps wherever context is missing.

That flagging is the single most important part of the prompt: Claude should explicitly mark every claim that does not follow directly from the code it read, instead of presenting a plausible sounding guess as a fact. The result is a document that cleanly separates two categories of content, verified technical facts and open questions for the team, which speeds up the subsequent human contribution considerably.

{
  "generated_by": "claude-code-analysis",
  "generated_at": "2026-06-18T08:40:00Z",
  "project": "mironsoft.de",
  "sections": [
    {
      "title": "Project Overview",
      "status": "verified",
      "source": "composer.json, docker-compose.yaml"
    },
    {
      "title": "Local Setup",
      "status": "verified",
      "source": "bin/start, compose.dev.yaml"
    },
    {
      "title": "Architecture and Module Overview",
      "status": "verified",
      "source": "app/code/*/etc/module.xml"
    },
    {
      "title": "Deploy Sequence",
      "status": "verified",
      "source": "CLAUDE.md"
    },
    {
      "title": "Why Mironsoft_Core was chosen as the base dependency",
      "status": "needs_human_input",
      "source": null
    },
    {
      "title": "Module owners and points of contact",
      "status": "needs_human_input",
      "source": null
    }
  ],
  "open_questions_count": 2
}

4. First-week checklist: setup, access and a first task

One of the most valuable pieces of any onboarding documentation is a concrete first-week checklist: which access is needed, which Docker containers must run, which command starts the local environment, and which first, clearly scoped task is suitable for verifying the setup. Claude can derive such a checklist directly from the existing setup scripts, the Docker Compose file and the wrapper scripts in the bin/ directory, rather than writing it from memory.

The advantage over a hand written checklist shows up mainly when things drift: when a new bin/ script is added or a Compose service gets renamed, a manually maintained list goes stale unnoticed, while a checklist generated from the actual state of the repository picks up that change automatically the next time it is regenerated. The checklist does not replace a personal walkthrough, but it noticeably reduces the number of follow up questions about pure mechanics, such as "which command starts the container".

#!/usr/bin/env bash
# First-day setup checklist derived directly from the actual repo state,
# not from a hand-written list that quietly drifts out of sync

set -euo pipefail

echo "1. Clone the repository and copy the local env file"
echo "   cp env/dev.env.dist env/dev.env"

echo "2. Start the Docker stack (Mark Shust setup)"
echo "   bin/start"

echo "3. Import a sanitized database dump"
echo "   bin/mysql < var/backups/latest-sanitized.sql"

echo "4. Verify the storefront responds"
until curl -sf http://localhost/ > /dev/null; do
  echo "   waiting for the container to become healthy..."
  sleep 3
done
echo "   storefront reachable, setup verified"

echo "5. First task: fix the failing test in tests/Unit/ExampleTest.php"

5. What only the team knows: decision history and unwritten rules

However thorough a codebase analysis is, there remains an entire category of knowledge no language model can derive from code alone: why a particular technical decision was made, which alternative solution was deliberately rejected, and which client pushed for a special rule that now looks like an arbitrary exception in the code. That knowledge often exists only in the heads of individual team members, in old ticket comments, or in Slack threads that no automated scan captures.

Being honest about this limit is essential for the credibility of the whole document: an AI draft that fills a context gap with a plausible but invented explanation is more dangerous than a visible gap, because new developers will trust the invented explanation and carry the wrong assumption forward. That is why every good prompt should explicitly instruct the model to flag decision reasons that are not present in the code or supplied documents as open questions for the team, rather than inventing them.

6. The hybrid workflow: AI draft, review and human input

A workflow that actually holds up combines AI drafting and team knowledge in a fixed order instead of mixing the two. First, Claude produces a draft from the codebase with clearly flagged open questions. Then an experienced team member reviews the draft, corrects technical inaccuracies, and answers the flagged questions in a short, dedicated session, instead of answering them piecemeal in chat messages over several weeks. Only after that is the document versioned in the repository and used as part of the onboarding process.

This works best as a small workshop with two or three experienced team members going through the AI draft together: discussing whether a claim the model made is actually correct often surfaces additional, previously unspoken assumptions that would otherwise never have been written down. The AI draft acts as a conversation anchor, putting concrete statements up for discussion instead of starting from a blank page, which teams tend to put off for a long time.

#!/usr/bin/env node
// Flags PRs that add a new Magento module without touching the
// onboarding guide, so the module list does not silently go stale

const { execSync } = require("child_process");

const base = process.env.GITHUB_BASE_REF || "main";
const changed = execSync(`git diff --name-only origin/${base}...HEAD`)
  .toString()
  .trim()
  .split("\n");

const newModule = changed.some((f) =>
  f.match(/^src\/app\/code\/[^/]+\/[^/]+\/registration\.php$/)
);
const onboardingUpdated = changed.some((f) => f === "docs/ONBOARDING.md");

if (newModule && !onboardingUpdated) {
  console.error(
    "This PR adds a new module but docs/ONBOARDING.md was not updated. " +
    "Add the module to the overview or confirm it needs no onboarding entry."
  );
  process.exitCode = 1;
}

7. CLAUDE.md as a living onboarding document for humans and AI

Projects that already work with Claude Code have an obvious dual use available: the CLAUDE.md file that Claude reads as system context in every session can double as the central onboarding document for new human team members. Coding standards, the deploy sequence, CLI wrapper commands and module conventions, which already need to be phrased precisely for the AI instruction to work, are useful in exactly that precise form for humans who are new to the project as well.

The practical advantage of this dual use is a built in early warning system: when CLAUDE.md contains outdated commands or wrong paths, that does not first surface when a human goes looking for it, it surfaces earlier, because Claude Code visibly gives wrong suggestions or proposes commands that no longer exist in the current repository. That feedback loop, which a purely human facing document does not have, makes gaps between the document and reality visible faster than in a classic wiki that nobody actively tests.

8. Keeping onboarding docs current instead of writing them once

The biggest practical difference between a one-time onboarding document and one that stays useful lies not in the initial quality but in the maintenance over the entire life of the project. A document that never gets touched again after the first onboarding is potentially misleading after a bigger refactor, a new module, or a changed deploy sequence, and misleading documentation is often more harmful to new developers than no documentation at all, because it creates false confidence.

An effective but low effort mechanism is an automated check that verifies whether meaningful structural changes in the code, for example a newly added module, have a corresponding entry in the onboarding document. In addition, a fixed cadence, for instance quarterly, at which Claude is asked to rescan the current state of the code and check the existing text for discrepancies, helps far more than waiting for a random moment when someone happens to notice the drift.

#!/usr/bin/env python3
"""Warn when the onboarding guide is older than the newest module."""

import subprocess
from pathlib import Path
from datetime import datetime, timezone


def last_commit_date(path: str) -> datetime:
    output = subprocess.check_output(
        ["git", "log", "-1", "--format=%cI", "--", path]
    ).decode().strip()
    return datetime.fromisoformat(output) if output else datetime.min.replace(
        tzinfo=timezone.utc
    )


def main() -> int:
    doc_date = last_commit_date("docs/ONBOARDING.md")
    module_root = Path("src/app/code")

    newest_module_date = doc_date
    newest_module_name = None
    for module_xml in module_root.glob("*/*/etc/module.xml"):
        commit_date = last_commit_date(str(module_xml))
        if commit_date > newest_module_date:
            newest_module_date = commit_date
            newest_module_name = module_xml.parent.parent.name

    if newest_module_name:
        print(
            f"[STALE] {newest_module_name} changed on "
            f"{newest_module_date.date()}, onboarding guide is older"
        )
        return 1

    print("[OK] Onboarding guide is up to date with all modules")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

9. Onboarding approaches compared

The table below compares typical approaches to creating and maintaining onboarding documentation and shows where the hybrid approach of AI draft plus human input stands relative to the two purely manual or purely automated variants.

In practice, the purely manual and the purely AI-generated variants fail at opposite ends: purely manual documentation often stays incomplete because nobody finds time for the first draft, while purely AI-generated documentation without a review step creates false confidence. The hybrid approach combines the speed of AI analysis with the reliability of human review and is, in practice, the only approach that actually stays current over several months.

10. Summary

Creating onboarding documentation with AI mainly solves an activation problem: the jump from a blank page to a structured draft derived from the actual code. Claude can systematically scan the codebase, conventions and setup scripts, and delivers a skeleton within minutes that replaces weeks of manual gathering. The benefit is real and measurable in saved senior time, as long as the draft is treated as a discussion basis rather than a finished document.

That benefit turns negative, however, the moment decision reasons, team knowledge and open questions are left unaddressed, or the text is published without review. A workflow that holds up clearly separates verified technical facts from flagged open questions, involves experienced team members for the missing pieces, and anchors regular updates as a fixed part of everyday project work rather than a one-time action after the first onboarding.

11. FAQ: Creating Onboarding Documentation with AI