What is Claude Code? It Read a 340-Page Tax Spec For Me

By Lazar Milicevic · Published July 3, 2026 · 8 min read

I had a client invoice integration that needed compliant XML submitted to a national tax authority. The spec was 340 pages. 27 required fields. Nested schemas. Conditional validation that changes based on transaction type. A specialist contractor quoted three weeks. I gave the job to Claude Code and walked away.

Four hours later, a passing test was hitting the live regulatory sandbox with a schema-valid payload. Zero manual XML edits from me. Here's exactly how that worked, and why the same setup breaks if you skip the grounding step.

Claude.ai talks about your code. Claude Code operates on it.

Claude Code is a terminal agent that runs inside your project folder with direct access to your files, database, API keys, and sandbox credentials. It doesn't return suggestions you copy back — it writes files, runs curl, parses PDFs, edits your repo, and hits real endpoints. That's the whole distinction.

The workflow difference in practice:

• Claude.ai (chat): you paste a snippet, it returns a snippet, you paste it back into your editor, you run it, you paste the error back. Human-in-the-loop for every keystroke.
• Claude Code (agent): you give it a goal and the environment. It reads the files itself, runs the tests itself, reads the failures itself, patches itself, and reports back when it's done or genuinely stuck.

For a solopreneur, that gap is the difference between "AI helps me code faster" and "AI does the ticket while I'm on a sales call." One is a productivity tool. The other is a headcount substitute for tasks that used to require hiring.

The 340-page tax spec problem

Regulated invoicing is a good stress test because the failure mode is expensive. A malformed XML field doesn't just throw a stack trace — it gets your client's invoice rejected by the tax authority. Enough rejections and there are real penalties. This is why small businesses either avoid the integration or pay a specialist $8k–$15k to build it once.

The concrete shape of the problem for this client:

• 340-page PDF specification, mostly in dense regulatory prose
• 27 required fields per invoice, each with its own data type and length constraint
• Nested schemas — parties, line items, tax breakdowns, payment terms
• Conditional rules: certain fields are required only for B2B, others only when tax is exempt, others only for cross-border transactions
• A sandbox endpoint that returns validation errors as XML, not JSON, sometimes with error codes that map back to a section in the PDF

Nobody wants to read that PDF. Not me, not the client, not a junior. That's the exact task where an agent that can actually read source documents earns its cost.

The one prompt that did the work

I opened Claude Code in the project folder, dropped the spec PDF into docs/, and gave it a single instruction. Not a chain of prompts. One goal, with the environment already staged.

cd ~/projects/client-invoicing
cp ~/Downloads/tax-authority-spec-v4.2.pdf docs/
claude

Then in the session:

Read docs/tax-authority-spec-v4.2.pdf.

Goal: submit a compliant sales invoice XML to the sandbox endpoint
defined in .env (SANDBOX_URL, SANDBOX_TOKEN).

Do this:
1. Extract the required fields for a standard domestic sales invoice
   (transaction type = 01). List them with data types before writing code.
2. Generate Pydantic v2 models in src/models/invoice.py that mirror
   the spec's schema, including conditional validators.
3. Write src/builders/xml_builder.py that converts our internal
   Invoice object (see src/domain/invoice.py) to the required XML.
4. Write tests/test_sandbox.py that posts one invoice to SANDBOX_URL
   and asserts a 200 response with status="ACCEPTED".
5. Run the test. If validation errors come back, re-read the relevant
   spec section and fix. Loop until it passes or you're blocked.

Stop and ask before adding any dependency beyond pydantic, httpx, lxml.

That's it. No hand-holding, no field-by-field dictation. The prompt works because everything it references is real and reachable: the PDF is in the repo, the domain object exists, the sandbox credentials are in .env, the dependencies are pinned.

What actually happened in that 4-hour window

• Parsed the 340-page PDF and produced a field inventory before writing any code (I read it — it was correct on 26 of 27 fields; the one it missed was a conditional field the spec buried in an appendix)
• Wrote Pydantic models with validators for length, regex, and enum constraints
• Wrote the XML builder using lxml with namespace handling
• Posted the first test invoice to the sandbox
• Got back three validation errors (missing namespace prefix on one element, wrong date format on another, incorrect enum value for payment method)
• Went back into the PDF, found the sections that documented each error, patched the builder
• Re-ran the test. Passing. Wrote a short summary of the changes in the terminal.

Grounding beats prompting

This is the part most tutorials skip and it's the reason people say "I tried Claude Code and it hallucinated garbage." If I had given that same prompt without the spec PDF in the folder, the agent would have invented plausible field names, generated XML that looks right to a human, and failed validation in ways that are painful to debug because the shape is almost correct.

The mental model: Claude Code is only as good as what you put in front of it.

For a regulatory integration, the minimum grounding is:

• The official specification PDF or XSD in the repo
• At least one example payload from the authority's own documentation
• The sandbox URL and credentials in a .env file the agent can read
• Your own domain model so the agent knows what it's mapping from
• A test script that hits the real sandbox, not a mock

A useful CLAUDE.md at the repo root that tells the agent where to look:

# Project: client-invoicing

## Regulatory context
- Spec: docs/tax-authority-spec-v4.2.pdf (authoritative)
- Example payloads: docs/examples/*.xml
- Sandbox: SANDBOX_URL in .env, credentials in SANDBOX_TOKEN

## Rules
- Never invent field names. If unsure, quote the spec section.
- Always test against the sandbox before claiming a fix works.
- If a field appears in the spec but not in our domain model,
  stop and ask — don't guess a mapping.

The stop and ask rule matters. Left alone, an agent will fill gaps with reasonable-sounding assumptions. In regulated work, reasonable-sounding is the failure mode. Force it to surface uncertainty.

Where this workflow beats hiring a contractor

For a solo operator or a small team, the economics shift hard once you accept that the agent will do the reading. A quick comparison based on this specific job:

The API cost number is real. Sonnet-class usage for a project this size, with a long PDF in context and several tool-use loops against the sandbox, sits in the $25–$60 range depending on how many iterations the agent needs. Compared to $10k of contractor time, the cost is irrelevant. What you're actually paying for is the four hours of your own attention to check the output.

And when the tax authority publishes v4.3 of the spec next year — because they always do — you drop the new PDF into docs/, run the same prompt with "regenerate against the updated spec, keep tests passing," and it does the diff work for you. That's the compounding value.

The failure modes worth knowing

I've built enough of these to know where this workflow breaks. If you try it on your own regulated integration, expect these:

• PDF quality matters. Scanned or image-based PDFs where the text isn't extractable will silently fail. Run pdftotext spec.pdf - first and confirm real text comes out. If it's a scan, OCR it before you start.
• Conditional rules buried in appendices get missed. The agent extracts the main tables well but sometimes skips exceptions documented in footnotes. Always ask it to explicitly list conditional fields and cross-check one B2B and one edge-case invoice manually.
• Sandbox drift. Government sandboxes are sometimes weeks behind the published spec. If the agent generates spec-correct XML and the sandbox rejects it, don't let the agent "fix" the code to match a broken sandbox — verify with the authority first.
• Namespace and encoding bugs are the top XML failure. Even with a good spec, XML namespaces and character encoding trip up the first few tries. Budget an extra loop for these.
• Never commit .env. Obvious, but the agent will happily read and reference .env values. Make sure your .gitignore is right before you start a session.

Why bizflowai.io helps with this

Most of the client work I do through bizflowai.io is exactly this shape: a regulated document, an internal system that doesn't speak the regulator's format, and a small business that can't afford a three-week integration project. The pattern — spec-in-repo, agent-as-integrator, sandbox as ground truth — is how we ship compliance work for invoicing, tax reporting, and industry-specific data submissions across US small businesses in weeks instead of quarters. It's not a magic prompt. It's a boring, repeatable setup: ground the agent, cage it with a CLAUDE.md, and test against the real endpoint before anyone touches production.

The takeaway

When someone asks what Claude Code actually is, the honest answer isn't "AI autocomplete for developers." It's an agent that reads the documents you don't want to read, runs inside the environment you already have, and produces artifacts that pass validation against real systems. For a solopreneur without a compliance team or a senior engineer, that's the gap that used to force hiring. It doesn't anymore.

Point it at the spec. Point it at the repo. Give it sandbox access. Let it operate.

Want more like this?

I publish practical AI automation, GenAI engineering, and faceless content workflows on YouTube every week.

Subscribe to bizflowai.io on YouTube — never miss a new tutorial.

Planning an AI automation project or need a second opinion on your architecture?

Connect with me on LinkedIn — Lazar Milicevic, GenAI Engineer & bizflowai.io Founder.

Visit bizflowai.io for our services, case studies, and AI consulting.