AI coding agents now write most of the code in a financial model. What they can't do for you is decide what a good model looks like. This guide is about exactly that: what every part of a model does, why it is there, and how you steer an agent to build it the way you would.

I have spent thousands of hours building financial models in Python, at financial institutions and in open-source projects like the Finance Toolkit. The structure, the conventions and the testing approach in this guide come from that work, including the mistakes I learned the most from. Each chapter explains one component in depth, and how you work on it together with an agent.

The Journey of a Model

From your first lines of Python to a model that an agent can extend safely, each chapter builds on the previous one. Start at the beginning, or jump to the question you have right now.

1 Where do I begin? Getting Started Nail down the basics of Python, Pandas and NumPy, and learn when to let an assistant take over. Read chapter 2 What does a solid project need? Setting up your Project Dependencies with uv, linters, a Git workflow and the files that keep a model working for years. Read chapter 3 Where does each piece of code go? Structure your Model The Model-View-Controller pattern for financial models, and why it makes every change easy to review. Read chapter 4 What does good model code look like? Build your Model Naming, type hints and docstrings, and the financial choices to check in every change. Read chapter 5 How do I know nothing broke? Test your Model Recorded tests that flag every changed number, whoever changed it. Read chapter 6 How do I make an agent follow all this? Working with AI Instruction files, rules, Skills, hooks and MCP servers, with a ready-made kit. Read chapter

The Agent Kit

Free download

Teach any coding agent what this guide teaches you

Ready-made instruction files and skills that you copy into your repository. One AGENTS.md holds the rules from this guide (the structure, the conventions, the testing approach and the financial choices an agent should never make silently), and every tool's own file points to it. That way Claude Code, GitHub Copilot, Cursor, Codex, Gemini CLI and other agents all follow the same instructions.

Download the kit (.zip) Browse the files
  • AGENTS.mdAll instructions; read by Codex, Cursor, Copilot and most agents
  • CLAUDE.mdGEMINI.mdPoint Claude Code and Gemini CLI to the same instructions
  • .github/Copilot instructions, plus a rule for model files
  • .cursor/rules/Cursor rules, always on and for model files
  • .claude/skills/Four skills: add a metric, write tests, review a change, set up a project
  • .claude/settings.jsonA hook that formats and lints every edit