We recently built a payroll system for an IT services company with a growing team. Payroll had been calculated by hand every month, and payslips were emailed one by one. The company wanted a tool built for its own rules, owned by the company and run on its own infrastructure. The full story is in our payroll management system case study. This post is about what we learned along the way, including where AI helped and where it did not.
Lesson 1: The rules are the project
We expected the hard part to be the software. It was the rules. Staff were on different pay structures: fixed salaries, allowances that depended on role, deductions that varied by person and leave that affected pay in different ways. Some rules applied only to certain roles or only in certain months.
Those rules lived in people's heads and in old spreadsheets. Writing them down precisely, with examples, was the first real piece of work, and nothing else could be trusted until it was done. Every conversation that clarified a rule saved hours later.
If you are planning a similar project, start here. Before any code, write each rule in plain language with two or three worked examples from real payroll months. See how to automate payroll.
Lesson 2: AI is fast at turning clear rules into code
Once the rules were written down, AI turned them into first versions of calculation code quickly. This is exactly the kind of work AI does well: a clear specification, a familiar pattern and a way to check the result. Engineers then checked each rule against the finance team's examples.
The speed came from the written rules, not from the AI alone. When a rule was vague, the AI produced something plausible and wrong. When a rule was precise, the first draft was usually close. Clear inputs, good outputs.
Lesson 3: Let AI list the edge cases, then decide which matter
We asked AI to list edge cases for each rule: joiners in the middle of a month, partial leave, changes to salary partway through a period and more. It produced long lists, some of them obvious, some useful, a few irrelevant. We turned the ones that mattered into unit tests.
This was one of the most valuable uses of AI in the project. Thinking of edge cases is tedious, and people miss them when tired. AI does not get tired. People still had to decide which cases were real for this company.
Lesson 4: Tests are what make the numbers trustworthy
Every rule is in code, and every rule has tests. When a rule changes, the tests show exactly what else changes. That is what lets the finance team trust the numbers without redoing the arithmetic.
It is tempting to think of tests as a developer concern. In payroll, they are a business concern. They are the evidence that a change to one allowance did not quietly break a deduction for someone else. See how we review AI-generated code for why tests are central to our process.
Lesson 5: Design the review step around exceptions
The finance team uses the tool once a month under time pressure. So the main screen is the payroll run itself: its state, the totals and the exceptions that need a person, such as new joiners, unpaid leave or unusual deductions. A reviewer can open any employee from the run and see how each figure was reached.
We kept the interface plain on purpose. Payroll is not a place for surprises. Labels use plain payroll terms, and the steps follow the order of a manual payroll: inputs, calculation, review, payslips. Familiar order made the new tool easy to adopt.
Lesson 6: Email delivery is a project of its own
Payslips are generated as PDFs and sent in one batch from the company's own mail server. The first time we sent them from the self-hosted server, Gmail rejected them.
Fixing that meant building the server's sender reputation properly: reverse DNS for the sending address, SPF, DKIM and DMARC records, and forcing delivery over IPv4. Only then did payslips arrive reliably in every inbox. Each send is now recorded, so the team can see what was delivered.
It is the kind of detail that is invisible when it works and very visible when it does not, especially when the email contains someone's pay. If your product sends important email, plan time for delivery setup and testing.
Lesson 7: Keep a history of everything
Corrections and approvals leave a history, so questions can be answered from the record. Before, when an employee questioned a figure, the answer meant going back through spreadsheets and emails. Now it is a few clicks. Audit history is cheap to build at the start and expensive to add later.
Lesson 8: AI drafts, people edit, documentation gets done
AI drafted the guide for the finance team, explaining each step of a run in plain language. The team edited it before use. Documentation is often skipped on small internal projects. With AI doing the first draft, it took little time and it got done.
Where AI did not help
AI did not help us understand the company's pay rules, decide how the review screen should work or diagnose the email delivery problem from first principles. Those took conversations, judgment and experience. That pattern matches what we see on most projects. See why we build with AI, and what we still do by hand.
Takeaways
- Write rules down precisely, with examples, before building.
- Use AI to turn clear rules into code and to list edge cases.
- Test every rule. Tests are how the business trusts the numbers.
- Design review around exceptions, in a familiar order.
- Treat email delivery as real work.
- Keep a full history from day one.
If payroll or another monthly process eats your team's time, see our payroll automation solution and internal tools service, or tell us about it.
