Make the Codebase Explain Itself Before Anyone Writes Code

My squad works on the e-procurement platform of one of Indonesia's largest state-owned banks: vendor screening, tenders, contracts and invoices flowing into SAP, with multi-level approvals. It is a big, old codebase, and the hard part of a task is rarely the code. It is knowing what the business actually expects, and what else breaks when you touch something.

The gap I kept seeing: client requirements lose detail on their way to the engineer. By the time a task card reaches someone, the edge cases are gone. So I built a small pack of Claude Code skills that make the codebase explain itself, and that check a task before anyone starts coding.

1. Flow: the business process, written from the code

The first skill reads the routes, services, state constants and approval logic, and writes the business flow as a document a new engineer can read in ten to fifteen minutes. It draws the source-to-pay pipeline and one state machine per document type, and it ends with a ready-to-send list of questions for the business analysts: the places where the code is ambiguous or looks wrong.

FLOW.md     the business flow, readable in 10-15 minutes
            pipeline + one state diagram per document (mermaid)
            ends with questions for the analysts
flow.yaml   the commit it was generated from, so staleness is checkable
C4.html     context, container and component views in one file

The small file next to it records which commit the flow was generated from. Documentation about code goes stale quietly; this makes "is this still true?" a check instead of a guess.

2. Task check: vet the card before the code

The second skill runs at two moments: before coding, against the task card, and before merge, against the diff. It works in three steps.

• Is the flow current? If the code moved on, regenerate first.
• Gap analysis across seven categories, then an interview one theme at a time. Every gap ends as answered, a question for the analysts, or explicitly out of scope.
• Output you can act on: Given/When/Then acceptance criteria, plain-language questions for the analysts, a high/medium/low blast-radius checklist pointing at file and line, and suggested tests.

When something slips through to production anyway, it goes into a shared catalogue of edge cases, so the next check asks about it. The tool gets better from its own misses.

3. C4: architecture for people who don't read code

Management asked for a high-level view, so the third skill writes one self-contained HTML file with the context, container and component views, a table of relations backed by evidence from the code, and ranked risks.

I tried Mermaid's C4 diagrams first and dropped them: the automatic layout scatters arrows until the picture means nothing. The diagrams are laid out by hand instead, and a checker script plus a screenshot review gate the output before anyone sees it.

Two rules that matter more than the tools

1. Paste the client's request word for word on every card. Summaries are where the detail dies.
2. Vetting is the definition of ready. A card is not ready to build until the task check has run and its questions are answered.

The skill is not the point. The point is that "ready" now means something you can check.

What I would tell another lead

• Start with onboarding, not automation. The flow document paid off on day one: a new engineer gets the shape of the system before reading a single controller.
• Make the AI ask questions, not just answer them. The most useful output is often the list of things the code cannot tell you.
• Keep confidential output out of the tool. The skills live in a shared repo; the generated documents for the client stay where the client's code is.

I don't have a neat before-and-after metric to show yet, and I would rather say that than invent one. What I can say is that the questions arrive before the code does, which is exactly where they are cheapest to answer.