Jekyll2026-08-15T12:47:39+10:00https://dowdeswells.github.io/feed.xmlSoftware Development ThoughtsWhat's taking up my free time lately.Structured coding and refactoring2026-08-15T00:00:00+10:002026-08-15T00:00:00+10:00https://dowdeswells.github.io/2026/08/15/ai-excursion-part-5The goal

The separation of concern skill seems to be working quite well. The code does seem to be structured in a way that I understand and I’m reasonably happy with the quality. There are, however, quite a few occurrences of repeated code. Also the size of the classes can get quite large. I wonder whether a skill could find any improvements?

I’m going to work on this with the assumption that the AI knows all the concepts. It just needs me to tell it my preferences and priorities.

My first attempt at skill is a very simple one. Focusing on modular design, cohesion and coupling. So as not to make the skill too long I will throw in there a reference to Robert Martin’s Clean Code.

The first skill

Here is my first attempt at the skill.

structured coding skill

Structured Coding Definition

Consider the various levels of coding units, such as modules and classes and routines

The factors of well structured code are:

  1. high cohesion - A routine should do one thing and do it well
  2. low coupling - Minimizing dependencies and direct connections between different modules.
  3. no repeating code - Identify coding in routines that are very similar and work to extract a parameterized, reusable unit

The goals of structuring are:

Aim for modules that are focused on the inside (High Cohesion) and independent on the outside (Low Coupling). Modules communicate through simple, well-defined interfaces without needing to know the internal workings of other modules.

Clean Code

Reference Robert Martin’s (aka Uncle Bob) Clean Code

The outcome

Running the skill via the agent on just a single class the CosmosEventStore produced the desired effect. The repeated code was removed, and some other changes were made, but nothing outside of the class, which is what I specified in the prompt.

Gang of Four

I’m interested to know what I can get away with without writing too many words in the skill. I prompted the ai to look at the Cosmos event store and report on any Gang Of Four patterns that would go well with that code. The AI didn’t need any more explanation. It went through the Gang Of Four patterns individually and came up with a report. In the end the recommendation was a strategy and a builder. Unfortunately it then implemented them as internal sealed classes inside the main class, which only made the file bigger. I guess a skill somehow needs to apply judgement on file size and general reusability of utilities.

]]>More thoughts on Grilling2026-08-11T00:00:00+10:002026-08-11T00:00:00+10:00https://dowdeswells.github.io/2026/08/11/ai-excursion-part-4Grilling on a token usage requirement

I’ve just done a grilling session on a requirement to log token usage. Now that I have my blog up and running I can record my thoughts immediately. Firstly, while the grilling is powerful, if you deviate with a question, midstream it can get confusing as to what the AI has decided on your answers. Sometimes it needs to be told that you didn’t actually answer the question so that you can go back and review. Secondly, I was able to change my mind or introduce new or changed concepts, but I’m not fully convinced that this is a free flowing conversation.

As you watch the agents reasoning output you can sometimes see that it has made, or possibly made, a decision that you don’t agree with. For example in this case I could see that the batching of token usage records for a chat turn was not being considered. In the end the agent and I agreed this was a phase 2 concern. A pretty good agile outcome.

I think a full spec iteration would require multiple grilling sessions over the same spec, each with a limited scope for changes.

I wonder how a team would cope with the verification of a spec. Who would decide when the spec is complete and correct?

Maybe if you get so far down the wrong road it’s better to throw away and start again.

]]>Methodology2026-08-10T00:00:00+10:002026-08-10T00:00:00+10:00https://dowdeswells.github.io/2026/08/10/ai-excursion-part-2Keeping it real

After a few Vibe Code sessions with the DeepSeek API it is very easy to see how an enthusiastic individual could lose track of the source code for the solution they are building. Vibe Coding is an informal habit. For a reproducible outcome some guardrails are needed. The key to this is building a methodology.

  • Human Validation: Verify the source code. In fact get to know it. Human in the loop is not enough. Human in control is the goal.
  • Hardening: This is accomplished by developing a set of SKILLs for your AI agent. These are needed for requirements to specification and specification to implementation. Its an iterative task to get to a point where these SKILLs do the heavy lifting for the methodology.

AI Skills development

There are a lot of skills out there. I started by looking at 2 in particular.

The Matt Pocock Grill Me skill was a revelation. The iteration over the original prompt by DeepSeek was impressive.

The other skills were verbose and it was not apparant what value they were adding. To provide a deeper insight into this it’s better to develop them from scratch. This is, after all, a learning exercise.

I will focus on the specification to implementation since the Grill Me skill, even in its simplest form, produced a document of implementation slices. Here is the set from a session on adding OAuth to the expense tracker:

OAuth + BFF Design (grilling session outcome)

Status: implemented. All slices are done and green:

  1. Core per-user isolation — owner-keyed store/business layer, ICurrentUser seam, per-user sessions (implemented + deterministic tests).
  2. BFF auth plumbing — OpenIdConnect + cookie auth, /login /logout /api/user, [Authorize], current-user middleware.
  3. Dev identity provider — Keycloak in Docker (option 3, chosen after OpenIddict was ruled out: no OpenIddict version since 3.x has in-memory stores, and all versions hard-require HTTPS — see the blocked-attempt note below). Users/clients live in a realm import JSON; the BFF’s AUTH_AUTHORITY points at it.
  4. Frontend — login gate, user header, sign-out, 401 handling.
  5. Tests — ExpenseAgent.WebApi.Tests: deterministic fake-auth BFF tests + a real Keycloak e2e login test (skips when the container isn’t running). The full suite is green with and without the Keycloak container.
]]>SKILL: Layered design for separation of concerns2026-08-10T00:00:00+10:002026-08-10T00:00:00+10:00https://dowdeswells.github.io/2026/08/10/ai-excursion-part-3What’s it all about

I start with the end goal in mind. What i really need in the design phase is a clear set of interfaces that allow the parts of the software to be able to be iterated upon in isolation. A simple expression of this is:

agent layer  ──▶  business layer  ──▶  storage layer
 (translates)      (domain logic)      (persistence, injected)

Importantly the business layer does not depend on anything. For what it needs, it provides interfaces for the other layers.

ToDo - security, testing, refactoring

At this point the general code architecture is addressed but specific cross cutting concerns are a TODO. Specifically, looking at the source code I can see repeated code. I will address this as a priority and then move on to security hardening and iterating over the various testing phases.

I also don’t like the Microsoft AIAgent being exposed in the interface of the Agent layer. It ties to the implementation as Microsoft Agent Framework.

Testing has been touched on in this current version but i want a clear progression of test scopes including the ability to run every test in a docker compose - something a ci pipeline would possibly include before a deploy except I fear this may be a bit too much for most runners due to the need to startup a local SLM.

The full document, at the time of writing looks like:

separation of concerns

Layered Design for Separation of Concerns

A three-layer pattern for building AI-agent features cleanly. The rule of thumb: each layer only knows about the layer directly beneath it, and nothing below the agent layer knows that an AI exists.

agent layer  ──▶  business layer  ──▶  storage layer
 (translates)      (domain logic)      (persistence, injected)

The three layers

1. Business layer — Business/ (namespace …Business)

  • A class (*Service) with the business functionality: constructs domain objects (with sensible defaults), enforces business rules, orchestrates persistence through the injected store.
  • A validation mechanism (*Validator) for the input parameters: required fields, ranges, dates (e.g. reject future dates), defined enum values.
  • A result type (*Result) for operation outcomes: success + domain object, or a plain-language error. No emojis, no Markdown, no AIFunction — this layer returns domain objects only.

2. Data storage layer — Storage/ (namespace …Storage)

  • An interface (I*Store / I*Repository) plus a concrete implementation (in-memory, EF Core, SQL, …).
  • Injected into the business object’s constructor — the business class never news up its own store.
  • Pure persistence. No business rules (no future-date checks, no amount validation), no AI concepts. Swapping the implementation must not touch the other layers.

3. Agent-specific layer — Tools/ (namespace …Tools)

  • A translation class (*ToolActions): converts the AI tool’s raw string parameters (dates, ids, enums) into typed values, calls the business object, and formats the domain results into the Markdown/emoji responses the model reads.
  • A tool-registration class (*Tools): creates the AIFunctions with a name and a description (via AIFunctionFactory.Create) that tells the model when to call the tool and what parameters it needs.
  • All AIFunction, tool-description, and response-formatting concerns live here.

Workflow: applying this to a new feature

  1. Model the domain — a shared entity in Models/ (used by all three layers).
  2. Storage layer — write the interface, then a concrete implementation. Make it thread-safe if it is shared across sessions.
  3. Business layer — result type → validator → service class with the store injected in its constructor. Every business rule goes through the validator.
  4. Agent layer — one translation method per tool (raw strings in → typed business calls → formatted responses), registered with AIFunctionFactory.Create.
  5. Wire it up — register store + service in DI, pass the service into the agent factory. In this repo the agent project owns the composition root: 
    // ExpenseAgent/DependencyInjection/ExpenseTrackerServiceCollectionExtensions.cs
services.AddSingleton<ITransactionStore, InMemoryTransactionStore>(); // interface (ExpenseLib) → impl (Expense.Infrastructure)
services.AddSingleton<TransactionService>(); // business layer (ExpenseLib), store injected by the container
services.AddSingleton<AIAgent>(sp =>
    sp.GetRequiredService<AgentFactory>().CreateExpenseTrackerAgent(
        sp.GetRequiredService<TransactionService>()));
// WebApi: builder.Services.AddExpenseTracker(agentConfig);
  6. Test each layer — deterministic tests that do NOT need an LLM or API key:
    • Business layer: unit tests against the service (construct, validate, edit, remove).
    • Agent layer: invoke the AIFunction directly with a JSON-like argument dictionary, bypassing the model entirely.

Copy-paste templates

All templates live in templates/ (C# / .NET + Microsoft.Extensions.AI). Substitute the Transaction* names with your domain:

Template File Replace
Domain model templates/domain-model.cs Transaction → your entity
Storage layer (interface + in-memory impl) templates/storage-layer.cs ITransactionStore, InMemoryTransactionStore
Business layer (result + validator + service) templates/business-layer.cs TransactionResult, TransactionValidator, TransactionService
Agent layer (tool actions + AIFunction creation) templates/agent-layer.cs TransactionToolActions, TransactionTools

Reference implementation

This repository implements the pattern split across three projects — the AI-free core in ExpenseLib, the concrete storage in Expense.Infrastructure, and the agent layer in ExpenseAgent (which references the other two and composes everything):

  • Domain + business: src/ExpenseAgent/ExpenseLib/ — Models/Transaction.cs, Business/TransactionService.cs, Business/TransactionValidator.cs, Business/TransactionResult.cs (namespace ExpenseLib.*, no AI references)
  • Storage interface: src/ExpenseAgent/ExpenseLib/Storage/ITransactionStore.cs
  • Storage implementation: src/ExpenseAgent/Expense.Infrastructure/InMemoryTransactionStore.cs
  • Agent: src/ExpenseAgent/ExpenseAgent/Tools/TransactionToolActions.cs, src/ExpenseAgent/ExpenseAgent/Tools/TransactionTools.cs
  • Wiring: AgentFactory.CreateExpenseTrackerAgent(TransactionService) + the composition root ExpenseAgent/DependencyInjection/ExpenseTrackerServiceCollectionExtensions.cs (AddExpenseTracker), called from ExpenseAgent.WebApi/Startup.cs
  • Tests: ExpenseAgent.Tests/TransactionServiceTests.cs (business layer), ExpenseAgent.Tests/TransactionToolTests.cs (agent layer, no LLM)

Rules and anti-patterns

  • ❌ Agent tool methods reaching straight into the store — always go through the business object.
  • ❌ Business layer returning ❌/✅/Markdown strings — return a *Result; the agent layer formats.
  • ❌ Validation (future dates, positive amounts, required fields) living in the agent layer — it belongs in the *Validator, behind the business object.
  • ❌ Business layer referencing AIFunction, Microsoft.Extensions.AI, or tool descriptions.
  • ❌ A store without an interface — the business object must receive storage by injection.
  • ❌ Passing raw, unparsed strings into the business layer. Parsing (string → DateTime/Guid/enum) is translation and lives in the agent layer; validating parsed values against business rules lives in the business layer.

Quick check before you call it done

  • Does the business class construct and validate without any AI types?
  • Is the store injected via constructor, not instantiated inside the business class?
  • Do the agent tool actions only parse, translate, and format?
  • Do deterministic tests cover the business rules without an LLM or API key?
  • Can the storage implementation be swapped without touching the business or agent layers?
]]>Developing with AI, developing for AI2026-08-07T00:00:00+10:002026-08-07T00:00:00+10:00https://dowdeswells.github.io/2026/08/07/ai-excursion-part-1Goal: Agentic

I’ve decided to develop an application hosted on Azure. Developed, or should I say, co-developed with an AI agent and featuring some form of agentic processing.

The application is an expenses tracker. Something which has become slightly more pertinent given recent events.

My goal is to develop the application, and also to develop the processes via which I will employ the AI agent to help me code.

Coding Agent Harness: pi.dev

At work I was using Copilot installed into Rider for .NET development.

Reviewing the outcome and upon researching what is available, it has become apparent that a more simple tool is needed. Less clutter. Something in a terminal, something full screen. Focusing on the task in hand - agent work vs output review.

This is provided by pi.dev

Coding Agent: DeepSeek

pi.dev integrates simply with DeepSeek, just an environment variable with the DeepSeek API key It seems pretty good so let’s start there.

What have i got so far

The deployed Expense Tracker

I’ve been working on the code for a week. At this point I have a working expense tracker that runs an agentic loop with a register set of tools (mcp) that Add and edit expenses and income. The storage is implemented in a CosmosDB with an Event Sourcing design (which I will talk about later) which makes perfect sense for an auditable transaction record. There is a Github Action to deploy to an Azure Container App. OAuth users are provided by an Auth0 IDP.

AI Agent Costs

DeepSeek is really cheap compared to the others. I’m impressed. My total spend over this period is about $1.30. I did try Kimi K3 for one small task - adding keycloak as the dev IDP in docker compose. After $2.50 it still hadn’t worked through the problems so I stopped pi.dev (simply type in a new prompt to “stop what you are doing”) and changed back to DeepSeek which proceeded to finish it off with a tiny cost.

]]>