My Coding Agent Understands My Business Concepts
Deep-Dive Into a Setup That Works
At Atherio we offer leaders real time insights and intelligence around the dynamics of the people they lead and their own leadership effectiveness. Our mission is to bring every leader the wisdom they need in the moments that matter. What this means is that we are shaping an entirely new category of business concepts. Just bear with me for a while. I promise this matters and it’s not advertisement.
For instance, we have the concept of Dynamic Employee Engagement (DEE) which measures employee engagement through behavioral analysis of digital communication and calendar patterns.
The other core functionality is what we call the digital Leadership Development Index (LDI) which measures leadership effectiveness through behavioral analysis of the manager’s digital communication with his/her direct reports, peers, their own managers and other stakeholders.
Finally, we have our leadership nudges, which is essentially a proactive coaching system that delivers personalized, actionable prompts to leaders based on their team engagement and leadership data. Think of this as a Yoda on the shoulder of each manager that knows everything and has the wisdom to provide them with actionable insights.
How This Challenged My AI Assisted Engineering Workflow
From the early days of developing the entire system this reality posed some real challenges to me while trying to leverage Claude Code as my AI coding agent. The fundamental challenge is that LLMs are technically limited a lot by their training data. Ask any coding agent to implement you a social feed for a micro-blogging platform and it will provide you something reasonable output (yeah, I did this as a side-project so it’s not just an assumption).
The problem is I couldn’t just prompt my coding agent to implement me DEE or LDI. I couldn’t even ask it to implement sub-components of these complex features, because none of this is something that an LLM has been trained on.
One of the first things I did back in November was to start by first creating an extensive documentation on our desired features. I then enhanced that initial documentation after each planning session I had with Claude Code. In the end it became something that captured a lot of the business concepts and their code implementation including tons of machine-readable diagrams.
However, this became something very frustrating later as I needed to start every new prompt by providing specific references to the pieces of documentation that mattered for that specific work unit. That worked quite well but was very time consuming.
I’ve tried to optimize documentation consumption by creating documentation indexes that helped the coding agent understand better what pieces of the documentation mattered for a specific prompt and which not.
That also helped a lot, but I felt something was still missing. My coding agent needed to understand my business concepts from the get-go and optimize token consumption. As Claude Code evolved, I evolved my workflow with it and now I can confidently say that I have a coding agent that fully understands the business concepts and their implementation in code. So, here’s my setup.
From Heavy Documentation to Granular Skills
Thankfully, coding agents have evolved a lot in the past 7 months and the introduction of skills as a core concept drastically shifted the way I instructed Claude Code to work. Don’t get me wrong: documentation is still the central piece! What shifted is the way I instruct the coding agent to consume it.
My initial change was to create a dedicated skill for each of the main proprietary functionalities. Therefore, I created DEE, LDI, Nudges and Athi skills, along some other skills for some not that proprietary parts like the background job orchestration, authentication and authorization, the onboarding flow and security setup.
How this worked is that each agent was instructed on what part of the documentation to read, how to interpret it, where to look for specific topics and where to find the code implementation patterns and algorithms. That was already a huge improvement as I didn’t need to provide these instructions in every single prompt, no matter if just planning or execution. I made sure to create skill descriptions that caught most key words and phrases that should trigger the agent to use a specific skill.
I was very happy with the outcomes and my productivity boosted again. But along the way I noticed that context windows tended to fill up, and I wanted to optimize this.
The thing is that DEE, LDI, nudges de facto contain a lot of sub-components or areas. For instance, data ingestion and transformation for each of these concepts is a beast on its own. So is score calculation. So are the patterns I tended to use for the code implementation.
The natural evolution was to break those giant skills into several more focused ones. I ended up having a “DEE data ingestion skill”, a “DEE score calculation” skill, a “DEE coding patterns” skill and a bunch of other similar skills. The same was true for LDI, nudges and onboarding.
Again, this made a huge difference and for a couple of weeks I was totally happy. But then I bumped into another challenge: you can’t reference or simply import skills into other skills.
For instance if I needed to work on areas that involved both data ingestion and scoring, but I was not interested in coding patterns, the coding agent still read everything. That created context bloat that sometimes led to less reliable results.
From Granular Skills to Sub-Agents
What I ended up doing is creating sub-agents in Claude Code for each of the main functionalities. This means I ended up having a sub-agent for DEE, LDI, Athi, Nudges, Onboarding and a bunch of other stuff. So, how is this different from the initial setup with one skill per functionality?
Well, the difference is huge, but subtle. A sub-agent can effectively load and read skills on demand, just like the main agent. Therefore, having a sub-agent for each of these functionalities meant that my main agent can simply spin up the sub-agent it needs and the sub-agent, based on context, can then just use the skills it needs for that specific work unit.
One challenge I had with this approach was that sub-agents run in their dedicated context windows. This is very often a great thing but also resulted in some less reliable attempts on my side, because the summaries the sub-agents provided to the main agent were not always that helpful or didn’t contain the information that mattered.
The next steps were for me to tweak the sub-agents to provide the information in a certain format by providing exact instructions, a clear hierarchy of importance for different areas of that functionality and some reasoning guidelines.
Once more, I was thrilled with the outcomes! The outputs I got from Claude Code became very predictable even though obviously not 100% deterministic. There was one small area of improvement left.
My workflow makes a very clear distinction between planning and execution. I talked about this in my Cycle-Driven Development process and The Engineering Loop (drop a comment if you’d like to see a practical breakdown on how I approach this distinction).
In practice, this meant that I didn’t need all the coding related fluff of each functionality when I was planning and, obviously, the other way around.
From Skills and Sub-Agents to Rules
Claude Code has also the concept of rules, which I’m not aware it exists in other AI coding agents. The core idea is that rules treated with critical importance by Claude Code. More than MD files, documentation and skills. I have started to move all my coding guidelines to rules immediately after rules became available.
Therefore, the next logical step was to remove any lingering code implementation guidelines that were still lingering in my existing granular skills and sub-agents. That gave me finally the results I wanted, and my coding agent became fully aware of all the Atherio business rules and their implementation in code.
What This Means in Practice
Planning sessions changed first. The main agent no longer pulls in coding patterns or low-level implementation details when I just want to think through an approach. It loads only what the conversation requires, through the relevant sub-agent. A planning session that used to fill up context by hour two now stays clean through an entire afternoon. I finish full planning cycles in one go.
Execution became more reliable across longer work units. Before this setup, I would routinely see Claude Code lose track of architectural decisions made an hour earlier in the same session. Now, because each functionality lives behind its own sub-agent with explicit reasoning guidelines, the relevant context loads fresh when needed. Less drift. Don’t get me wrong: I still try to keep execution to very short lived context windows, but overall output predictability during work execution increased a lot.
And then there is the part that surprised me. Onboarding a new piece of work no longer requires me to mentally reconstruct what the agent needs to know. The system already knows. My job shifted from supplying context to specifying intent, which actually moves my entire work closer to architecture and further from prompt engineering.
A Final Caveat
There is one trade-off worth naming honestly.
Skills are surfaced to the agent through their descriptions. For Claude Code to reliably trigger the right skill, those descriptions need to be rich enough to catch the relevant keywords and phrases. In my setup, where multiple sub-agents each carry several granular skills, descriptions trend toward the verbose side. That is deliberate. A vague description means a missed trigger, which means manually loading the skill, which defeats the entire point.
Claude Code reserves roughly 1% of the model’s context window for the combined listing of all skill descriptions. When the listing exceeds that budget, descriptions for the least-used skills get dropped silently from the listing.
The skills still work. They just stop auto-triggering, because the agent can no longer see what they are for. On session start, you get a warning that looks roughly like this:
Skill listing will be truncated
N descriptions dropped (full descriptions kept for most-used skills)
(1.6%/1% of context): skill-a, skill-b, +N more
run /skills to disable some, or raise skillListingBudgetFraction
(currently 1%) in settings.json
I raised mine to 3% by setting skillListingBudgetFraction: 0.03 in settings.json. That costs me additional tokens but for my setup it is a tradeoff I make happily.
The reason is simple: the cost of one mis-triggered or skipped skill is higher than a few thousand tokens per session. I would rather pay the context cost up front than chase silent failures later. In the end, skills are infrastructure, and infrastructure is never free of charge.
If this gave you something worth thinking about, drop your thoughts or questions in the comments. And share the article with colleagues or engineering leaders who might find it useful.