The 17 context files for finance agents

Building finance agents in public special.

Hey Finance Engineers,

Alyona here. For those who found this newsletter recently: I’ve spent over a decade in finance, first in PWC, then as a CFO, then building Fuel, an FP&A software, and for the last two years, figuring out how AI fits into finance work. That’s what I write about here.

And right now, I’m living the biggest experiment of my career. After six years of building Fuel, we’re rebuilding the whole company around AI finance agents. We gave ourselves 3 months. Launch is September 29. I don’t know yet if it works. I share the journey in short weekly videos on LinkedIn.

But the videos are two minutes. And the things I most want to tell you, the actual finance engineering, don’t fit in two minutes. How we structure agent context. How we fight hallucinations.

So I’m going to try something: every now and then, between the regular skill issues, a building-in-public special. One piece of what we’re building, with everything you can take for your own work. This is the first one.

And it’s about the part that took us longest.

The context layer.

Some of you will remember the finance context file issue from June, one file that makes every AI answer about your business better. This is that idea, grown up. What happens when one file becomes a system.

Let’s go.

Agents fail on context

You can have the best model, the cleanest workflow, the most beautiful skill files, and the agent will still calculate revenue wrong. Because nobody told it how revenue works in this company.

Which streams exist. Which geographies, which SKUs. Whether that annual contract is recognized ratably or on delivery. What “payroll” even means when it lives under four names in the GL.

None of that is in the model. All of it has to be written down. And in most companies, it’s written down nowhere. It lives in the finance team’s heads, which is a lovely place for knowledge to live right up until someone goes on vacation.

So before our agents could do anything impressive, we had to do something deeply unimpressive for an AI company: sit down and write.

Why 17 context files, not one

The obvious move is one big context document. Everything about the company, one place, feed it to everyone.

We tried. And here’s the thing about context, too much confuses the model exactly like too little does. Hand an agent everything, and it wades through vendor classifications looking for a revenue rule. Like asking someone to find one sentence in a book by giving them the whole library.

So we split it. Seventeen single-topic files:

Why seventeen? Not a framework we invented. A pattern we kept meeting, six years, hundreds of companies, the same seventeen things that actually get asked about.

No agent we built reads all 17. Each one loads only what its task needs. Rev rec pulls the revenue model and accounting policy. AR pulls customers and contracts. The agent reads an index first, then takes only what’s relevant.

Faster. Cheaper (!). And accurate, because the model isn’t digging through vendor rules to find a recognition policy.

One topic per file. Every file carries an owner and a last_updated date. And the quality bar for the whole library, the line I’d frame and hang in the office:

If a new team member could answer a client’s question using only the context files and the data, the context is done.

Not “does it look complete.” Could a stranger run this company’s finance from what’s written here.

Where context comes from (the one-week collection plan)

Day 1-2: Mine what exists.

Your onboarding docs, board decks, accounting policy memos, that one Notion page someone made in 2023. Most companies have 30% of their context already written, just scattered.

Day 3: Run the kickoff interview.

We have a pool of questions we ask every customer on a recorded call; you can do the same with your own team. Ask your controller: how do we recognize revenue, stream by stream? Ask your analyst: which metrics have exclusions and why? Record it. The transcript becomes your first drafts - Claude turns a call recording into structured context files in minutes.

Day 4-5: Read what nobody can tell you.

Some rules are written nowhere. They live inside an Excel file’s formulas, a Google Sheet’s structure, a system’s settings. Open your main model and ask: what rules is this file enforcing?

Then apply the stranger test and fill the gaps it exposes.

You can’t just write your context once

A company is a living organism. Pricing changes. A new revenue stream appears. A vendor gets reclassified. The close gets a new step. And every one of those changes quietly invalidates a line in some file, without telling anyone.

We tested a format where our finance engineer refreshes each customer’s context manually. The verdict: at least once a month, something needs updating. Every time. Small edits, usually. Never zero.

Which means context isn’t a setup task. It’s a relationship. You don’t write it once and frame it, you keep showing up, or it stops being true.

So the next thing we’re building is a context-updating agent.

It watches where the team communicates, Slack, email, calls, drafts the updates, and before anything changes, sends them to a human for approval: the CFO, the Head of FP&A, or our finance engineer. Regular readers know the religion by now. The agent drafts. A human signs off. Even for the context itself. Especially for the context itself.

Nothing here stays stable. That stopped being frustrating the day we accepted it and started designing for it.

Steal the structure

You don’t need 17 files to start. You need this:

1. One topic per file. The test: could an agent load just your COA mapping without reading everything else?
2. Every file has an owner and a date. Context without an owner rots. Context with an owner just rots slower, which is the best anyone can promise.
3. Write until a stranger could answer. If a new hire could answer a question from your context alone, it’s done.
4. Schedule the refresh. Monthly, minimum. Put it in the close checklist, or it won’t happen.

Start with three files: your business model, your COA mapping, your metric definitions.

The wider point

Everyone asks me what’s hard about building finance agents. They expect the answer to be the AI.

IMHO, it’s not the AI. The hard part is that most companies have never written down how their own finance works. The agents just made it visible.

Which is the funny part, honestly. The work we’re doing right now, turning judgment into files, would be valuable in a world with no AI at all. It’s the documentation every finance team was supposed to write and never had time to. The agents didn’t create the need. They were the deadline.

Subscribe (and stay for the ride)

If you made it this far, you’re one of us. Subscribe for the weekly drop and these specials.

Every issue: my real builds, step by step - the prompts, the skill files, the screenshots, and the mistakes I made. Plus interviews with finance engineers, starting soon.

Pro subscribers get the full library: every skill file and prompt from every issue, deeper tutorials and behind-the-scenes builds, and the subscriber chat, and the .md files.

→ If you’re a vendor and you genuinely have something to offer this audience, email me at team@thefinanceengineer.io or DM me on LinkedIn.

— Alyona