DEV Community: Jerrett Davis

Vibe Engineering: Solving Small Cross-Cutting Concerns

Jerrett Davis — Tue, 14 Jul 2026 05:16:33 +0000

This article was originally published on my blog.

Vibe Engineering: Solving Small Cross-Cutting Concerns

I've been enamored by AI technologies far before the current generation of generative large language and diffusion image models hit widespread popularity in the early 2020s. Early in my career, I worked as a developer for a local Oil & Gas focused software company. One of the wings that they ultimately spun off into its own organization revolved around performing predictive data analytics on the massive datasets we'd accumulated across our various customers. Eye-opening stuff. Through properly trained models, the company was able to predict all sorts of failure modes, workflow trigger-points, and actionable business insights. The types of decisions that could be made off of these seemingly meaningless data streams changed how I thought about what software could do.

After I left that company, I joined a local healthcare organization. We built incredibly insightful visualizations, reports, and dashboards with our wealth of data. We only dipped our toes into training models for actionable predictions, but even those small exercises proved worthwhile. Outbreak forecasting built atop our wide-reaching care network let us glean and plan for valuable resource allocations months in advance.

A few years later, I found myself working back in oil and gas, this time at a company in a different sector of the field. They too were leveraging AI, training models on pipeline defects, failures, and inspections. This was their bread and butter. Every advancement yielded dividends.

As the clock ticked ever forward, I landed at yet another organization right as the first real generations of AI-assisted coding tools hit our IDEs. Software focused, this company planted its stake alongside giants like OpenAI's ChatGPT with our own growing suite of AI-assisted offerings. Once again, the capability of these technologies captivated me.

Around this same time, I started really tinkering with local Large Language Models and diffusion-based image generation. Ollama. Stable Diffusion. Anything I could get my hands on. I was excited enough about the possibilities that I built myself a new PC: a GeForce RTX 4090, 128gb RAM, an Intel i9 14900k (ouch), and a whole bag of other goodies.

I spared no time getting the machine setup with tooling, utilities, frameworks, and libraries. As the various coding models grew more capable, I found myself leaning into them more, allocating larger and more nebulous tasks their way. For the most part, I used them like a friendlier, more interactive StackOverflow compatriot. I still performed the vast majority of the actual work.

Then came the last quarter of 2025. I received an offer from another local company. I wasn't exactly looking, but I'd heard great things about the organization. They serenaded me with songs detailing near-endless problems in need of targeted, efficient solutions. Never one to shy away from an interesting challenge, I took the plunge. I quickly found myself back in the office, up to the eyeballs in new codebases and problems I'd never quite encountered before. Sure, the ingredients were familiar. I'd seen variations of these problems throughout my career. But rather than cooking exquisite enterprise dishes, I found myself staring at gas station spaghetti.

To my coworkers' surprise, I love spaghetti. Paradoxically, perhaps. It was one of my favorite dishes growing up. Unless there was lasagna on the menu, you could rest assured I was getting spaghetti. I loved it so much that I learned to cook it from scratch before I could competently solo-read a Harry Potter novel. Unsurprisingly, spaghetti code was also my first approach to programming, many moons ago. And here I was, hailing from the hometown of the late Tulsa Spaghetti Warehouse, staring back at an all-you-can-eat buffet.

So I got to chomping.

Bite after bite, I picked up forks-full of noodles and slurped them up. Meticulously. I started putting names to the dishes. Angel-hair. Spaghettini. Spaghettoni. At the risk of beating an already horrifically abused metaphor, I continued tearing apart one dish at a time. Every second of downtime between onboarding tasks became an opportunity to absorb as much as possible. Not just from the business perspective, but more importantly, from the architectural view.

The software was home-grown, home-cooked, home-eaten. We had to internally digest it all. The team had mostly come up through the company, many having been there for 15, 20, 30+ years. The code had evolved alongside the company and the individuals who shaped it. Invaluable knowledge lived within those repositories. But it was unstructured. Unrefined.

There were (and still are) hundreds of codebases comprising the enterprise stack. They're managed by separate and overlapping teams, all focused on propelling the business forward. As the company grew, so did the code. As requirements changed, so did the implementations.

Littered throughout various repos, you'll find comments. Some truthful. Many lying. All purporting to guide you through a forest of overlapping, stateful, static, threaded operations that seem to have sprouted at random. You clone. You touch. You grep. You cry. You prototype. You bargain. You claw your way through discombobulated systems until, slowly, light begins to shine through the ever-thinning limbs.

And you start to make sense of what you're looking at.

Not a forest. No. Something similar, but different. Something closer to a series of massive, interconnected, cautiously cohabitating fungal colonies. Myriad mycological monstrosities expanding into every suitable niche upon which their spores land. As you delicately disentangle their interwoven mycelium, the operation turns into something like a vivisection. Laid bare on the table, the endless nerve-like tendrils begin to make some semblance of sense.

Slowly but surely, different domain concerns start growing defined boundaries. Lists upon lists are made of identified cross-cutting concerns, domains, state mechanisms, authoritative sources of truth. Chaos soon begins to look a lot like patterns...

Little Architectural Building Blocks

Architectural building blocks and design patterns are nothing new. Hundreds, if not thousands, have been coined over the years. One of the "bibles" on the subject, Design Patterns by Erich Gamma, Richard Helm, Ralph Johnson, and John Vissides, came out while I was still largely quadrupedal. I was probably just taking my first few steps.

Despite the antiquity of such wisdom, employing these practices isn't the default operating mode for most developers. This continues to surprise me. Most people don't work in the field of their passion. They don't go home and continue thinking and dreaming about their topic of study. Instead, they chase the highest paying fields or follow whatever aptitudes they happen to possess. Silly things like that.

For better or worse, I was never instilled with such predeterminations.

Ever since discovering programming in my pre-tweens, I've been intent on wielding that hammer to sink every nail I can find. Over that multi-decade endeavor, I've hit a lot of nails. Also screws. Staples. Thumbs. Drywall. And other imperfect targets. Through that repeated practice (and self-injury), I've managed to beat in a few hard-earned lessons:

"Good code" is an ever-moving target, but good architecture is eternal.
You cannot truthfully and confidently deliver a unit of work without pre-defined and validated inputs and outputs.
Design a system to solve a problem, not to do a task.

"Good code" is an ever-moving target, but good architecture is eternal

Anyone who's been writing code for longer than an industry-standard release cycle knows things change fast. One week everyone's shoveling the latest ECMAScript hotness down your throat. The next, you're in an intense battle between Rust, Zig, and a bottle of dark liquor. Frameworks, languages, and libraries are a bit like running down to your local big-box hardware store trying to settle on power tools. Certain tools are fantastic for specific problems. You'll find more or less capable versions of similar tools across different brands. The choice matters, but not as much as people think.

It's often stated that premature optimization is the root of all evil. Agree or disagree with that sentiment, I believe most can agree on one thing: a problem solved via an imperfect solution beats the problem existing unabated.

What hasn't changed in the 60+ year span of our field? The components of good architecture. From the earliest beginnings, our tooling, languages, and approaches grew around the problems code solved and the strategies used to solve them. Put whatever label you want on the organization: Clean, Hexagonal, Vertical Slice, Domain Driven. The core tenets of creating declarative, functional, problem-domain-centric solutions have held steady through a blustering whirlwind of technological innovation.

I want to linger on "declarative" for a moment. It's become central to how I think about code quality.

Declarative code describes what should happen, not how it happens. It reads like a specification rather than a set of instructions. It's flat rather than nested. Composable rather than procedural.

Consider the difference:

// Imperative: a sequence of instructions
var user = GetUser(id);
if (user != null)
{
    var permissions = GetPermissions(user.RoleId);
    if (permissions != null && permissions.Contains("admin"))
    {
        var report = GenerateReport(user);
        if (report != null)
        {
            await SendEmail(user.Email, report);
            LogSuccess(user.Id);
        }
        else
        {
            LogFailure(user.Id, "Report generation failed");
        }
    }
}

// Declarative: a description of what should happen
await Given(userId)
    .Select(GetUser)
    .Where(user => user.HasPermission("admin"))
    .Select(GenerateReport)
    .Match(
        some: report => SendEmail(report).Then(LogSuccess),
        none: () => LogFailure("Report generation failed"));

The declarative version is flatter. No nesting. Each step is a transformation or filter. The flow reads top-to-bottom without branching into ever-deeper indentation levels. You can understand what it does by reading the method names. No need to trace through conditional logic.

This isn't just aesthetic preference. Flat, declarative code is easier to test because each step is a pure function. Easier to modify because you can add a step without restructuring everything around it. And crucially for our purposes, it's easier for agents to produce correctly. An agent generating the imperative version has to track state, manage nesting levels, handle the combinatorial explosion of possible paths. An agent generating the declarative version? It just chains transformations.

Package it however you like. As long as your solutions adhere to fundamental software engineering principles, your code can transcend whatever mortal coil its ecosystem imposes upon it.

You cannot truthfully and confidently deliver a unit of work without pre-defined and validated inputs and outputs

How can one begin to design a system if they don't know what they're building?

Too often I see developers blindly feeling their way through a codebase. They coordinate internal and external systems, real and simulated hardware, debuggers, and various other tooling just to pinpoint where they need to work. Then, once they've settled on their platform, they start blindly smashing atoms together hoping to yield something usable.

Experimentation is great. It's one of the foundations of our field. But experimentation is not for production work.

That's not to say you can't conduct experiments in production. I have an entire framework dedicated to that cross-cutting concern. But writing and performing experiments around the periphery of your implementations? That's the duty of your testing framework. If you find yourself probing instead of going directly to the test encapsulating your concern, you're working in a malignant, terrifying codebase. Rather than having a system shaped around external business concerns (business-provided inputs, service-provided outputs), you have a black box that requires action to validate. Like trying to guess the components of a modern art shadow projection by staring solely at its stain upon the wall.

When a developer needs to write code within an application, be it a new feature, bug fix, or otherwise, it's their duty to ensure they have clearly laid out expectations. Paramount among these: expected inputs (configuration, user inputs, workflow steps) and expected outputs (actions performed, values returned, errors that can be thrown). If experimentation is necessary to determine these parameters, that experimentation should be specific, documented, time-bound, with concrete deliverables. Those deliverables should then be cemented through business-relevant behavior-driven tests that enshrine the knowledge gained and mirror the documented requirements.

Design a system to solve a problem, not to do a task

I've learned a lot of skills over the years. Varying usefulness. If you need your floor tiled or your cat needs a crocheted vest, I may know a guy who can give some pointers.

But despite my obsessive compulsion to absorb information like a precious commodity, I lack any desire to repeatedly do things. Don't get me wrong. I can. I've been writing code for decades. But repetitive, monotonous tasks bore me to tears. So I've always tried to learn how to do something, improve it in some way, quantify it, and then automate it as much as humanly possible.

I'm prone to overusing metaphors. No exception here: I never want to do the digital equivalent of drywall.

Placing, finishing, and painting drywall are all technically simple endeavors on their surface. Give a sufficiently motivated greenhorn a couple weekends and they'll put up work that competes visually with career tradesmen. That says nothing for their speed or accuracy, or their need to redo tasks as they learn. But the finished product can ultimately be indistinguishable to an end customer.

Thing is, like many general contractors, I never set out to master one skill. I went out to solve problems and move onto the next. As I found more problems, my skills refined. My approaches improved. In isolation, that's a sustainable model. But over time, across many organizations and codebases, you'll invariably find yourself solving the same problems at a different place with a different toolset. You'll be putting up drywall, mud, and paint rather than selling and refining your new array of drywalling, mudding, and painting robots.

When solving problems, the work is rarely done in a vacuum. Developers start to get an itch that they've seen something before. I implore you: don't ignore it. Don't just copy and paste the solution that worked last time into the new class with a couple tweaks. Step back. Solve the bigger problem.

And this is where the modern era offers us something genuinely new.

Enter Agents

AI agents have amazing potential. But like overzealous, over-studious summer interns, they lack refinement, direction, and context.

That load-bearing poster keeping this place standing for the last 20 years? To them, it's just ugly, dated decor of a bygone era, ripe for paving over to make their mark. Within their sponge-like monolith of training data, they've accumulated vast wealth of knowledge. But it's locked away behind ear worms, secret incantations, and raw willpower. These agents are dang near capable of solving any singular task. Unlike the fleshy meatbags that wrote them, though, they lack the criticality, forethought, and analysis paralysis that keeps us humble. That ongoing game of chicken with imposter syndrome? They don't play it.

Once a problem becomes sufficiently large, it usually becomes multiple problems. Like a cancer metastasizing through the body, problems grow. They multiply. They cripple otherwise healthy solutions. Understanding how to leverage agents to break your problem down and distill it into its most basic essence? That's the key.

You cannot let them behave like chemo, attempting to find and fix every issue at once. You have to create a single, solvable, provable domain. Then you set them to work there.

The scope and scale of that domain will vary. Enterprise organizations have their own platforms. Their own logging wrappers, observability, configuration, options, feature flagging, messaging, and so much more. The second something leaks into multiple applications, it's time to figure out how to carve it out. Once a standard has been set, it's much easier to keep it contained, provable, and validated.

The Intern Analogy (Extended)

I keep coming back to the intern metaphor because it's genuinely the most apt comparison I've found.

A fresh intern shows up on day one with a head full of textbook knowledge. Four years of academic projects. And absolutely zero understanding of why your production database has a table called tbl_Users_OLD_DONT_USE_2019. They're capable. They're eager. They will absolutely demolish your carefully maintained naming conventions if you don't give them explicit guidance.

Agents operate the same way.

They've "read" more code than any human could in a lifetime. They know seventeen different ways to implement a repository pattern. They can recite the Gang of Four like scripture. But they don't know that your company uses ICommandHandler<T> instead of IHandler<T> because someone made that decision in 2017 and it stuck. They don't know that the Utils folder is actually load-bearing legacy powering three critical batch jobs. They don't know that Jerry from accounting will lose his mind if you rename the GetReportData stored procedure because he's been calling it directly from Excel for seven years.

Context is everything. And context is precisely what agents lack until you give it to them.

Tools, Not Decisions

There's a fundamental distinction in how you can leverage agents that took me longer to articulate than I'd like to admit.

You want agents to build tools that you validate. Not to make decisions that you trust.

The difference is subtle but profound. When an agent makes a decision directly (choosing an architecture, selecting a library, determining a business rule), you're trusting its judgment. As we've established, agents have plenty of knowledge but questionable judgment. They don't know your context. They can't weigh your constraints. They'll confidently recommend the "best practice" solution that's completely wrong for your situation.

But when an agent builds a tool? The dynamic shifts entirely.

The tool has inputs and outputs. It can be tested. Validated. Run against known cases and verified to produce correct results. You're not trusting the agent's judgment anymore. You're trusting your own ability to verify the tool's behavior.

This is why I've become increasingly obsessed with having agents build source generators, analyzers, and code scaffolding rather than writing application code directly. A source generator is a tool. It takes input (your domain model, your configuration, your conventions) and produces output (the boilerplate code you'd otherwise write by hand). You can inspect that output. Test it. Verify the generator produces correct code for all your known cases.

Compare this to having an agent write your repository implementations directly. Now you're reviewing each repository individually. Trusting that the agent understood your conventions for this specific case. Hoping it didn't introduce subtle bugs that won't surface until production.

With a generator, you validate the generator once. Then it produces correct code forever, across all your entities, without additional review. The agent helped you build a tool, and the tool does the work. You validated the tool's logic, not the agent's judgment.

This principle extends beyond source generators. Configuration validators. Migration scripts. Test scaffolds. Documentation generators. Any time you can have an agent build a tool that you validate rather than making decisions you trust, you're in a better position.

The mantra I've adopted: "Agents build tools. Tools do work. I validate tools."

Scoping the Work

The trick, then, is to scope your agent's work to a domain small enough that context can be fully provided, yet large enough that the work is meaningful. This is not unlike the advice given to junior developers: don't let them architect the whole system, but don't insult them with busywork either. Find the Goldilocks zone where they can produce real value with appropriate guardrails.

For me, that zone tends to be cross-cutting concerns. Not the core business logic (that requires too much institutional knowledge), and not simple CRUD operations (those are usually faster to do yourself than to explain). The sweet spot lies in the infrastructure layer: the logging wrappers, the configuration abstractions, the messaging contracts, the feature flag interfaces. These are bounded problems with clear inputs and outputs, well-established patterns in the broader ecosystem, and minimal business-specific context required.

And crucially, these concerns lend themselves to the "tools, not decisions" approach. A logging wrapper is a tool. A configuration binder is a tool. A message serializer is a tool. You can define what these tools should do, have an agent implement them, validate they work correctly, and then trust them going forward. You're not asking the agent to make business decisions. You're asking it to build infrastructure that you can verify.

Consider a logging wrapper. Every enterprise application needs one. The requirements are almost universal: structured logging, correlation IDs, log levels, maybe some redaction for sensitive data. The problem is well-understood, the patterns are documented, and an agent can produce a solid implementation if you give it your specific constraints (target framework, existing dependencies, naming conventions, test requirements). More importantly, you can write tests that verify the wrapper behaves correctly: does it include correlation IDs? Does it redact sensitive fields? Does it respect log level configuration? These are all verifiable properties of a tool.

Compare that to implementing a new pricing algorithm. The agent would need to understand your product catalog structure, your customer segmentation model, your promotional rules, your tax jurisdictions, your integration points with the billing system, and probably a dozen other things that live in the heads of people who've been there for a decade. That's not a bounded problem. That's a swamp. And worse, it's a decision problem, not a tool problem. The "correctness" of a pricing algorithm depends on business judgment, not technical verification.

The Vibe Engineering Workflow

I've started calling my approach "vibe engineering" (somewhat tongue-in-cheek) because it's less about prescriptive methodology and more about cultivating the right relationship between human architect and AI assistant. The "vibe" is the combination of context, constraints, and creative latitude you establish before any code gets written.

The workflow looks something like this:

Identify a cross-cutting concern that appears in multiple places
Report on its current state (how it's implemented, where it varies, what problems it causes)
Plan the extraction (define boundaries, interfaces, contracts)
Build the solution (iteratively, with human review at each stage)
Maintain the solution (documentation, versioning, evolution)

Each of these stages has its own dynamics when working with agents. The first two (identify and report) are where agents truly shine, because they can process vast amounts of code faster than any human. The middle stage (plan) requires heavy human involvement, because this is where architectural decisions get made. The build stage is collaborative, with the agent doing the heavy lifting under human supervision. And the maintenance stage is where the investment pays dividends, because a well-documented, well-tested solution can be maintained with minimal ongoing effort.

Let's dig into each of these stages.

Identifying Cross-Cutting Concerns

The first step in any extraction effort is knowing what to extract. This sounds obvious, but in practice, cross-cutting concerns have a way of hiding in plain sight. They're the code patterns you've copied so many times they feel like native syntax. They're the utility classes that exist in seventeen different namespaces because everyone needed one and nobody thought to check if it already existed. They're the configuration patterns that vary just enough between applications to be annoying but not enough to be obviously wrong.

Teaching an Agent to See Patterns

Agents are exceptionally good at this phase of the work. Give them access to a codebase (or several), provide some guidance on what you're looking for, and they can surface patterns faster than any human could through manual grep sessions.

But here's a nuance that ties back to our "tools, not decisions" principle: for one-off analysis, having an agent describe what it finds is fine. For ongoing pattern detection, you want the agent to build you an analyzer that you can run repeatedly. The difference matters.

If you ask an agent "what HTTP client patterns exist in this codebase?" you'll get an answer based on its current understanding of the code at this moment. If you ask an agent "build me a Roslyn analyzer that detects non-standard HTTP client instantiation patterns," you get a tool you can run in CI, that will catch new violations as they're introduced, and whose detection logic you can inspect and verify.

For the initial discovery phase, conversational analysis is perfectly appropriate. But once you've identified a concern worth tracking, consider whether the detection logic should become a tool.

The key is being specific about what constitutes a "cross-cutting concern" in your context. For a new codebase, I typically start with a prompt structure something like this:

Analyze the following repositories for cross-cutting concerns.
A cross-cutting concern is any functionality that:
1. Appears in multiple applications or services
2. Is not core business logic
3. Could reasonably be extracted into a shared library
4. Currently has inconsistent implementations across the codebase

Focus specifically on:
- Logging and observability patterns
- Configuration and options binding
- Error handling and exception management
- HTTP client usage and resilience patterns
- Caching strategies
- Validation approaches
- Mapping and transformation utilities

For each concern you identify, provide:
- Where it appears (specific files/projects)
- How implementations vary
- What problems the inconsistency causes
- A preliminary assessment of extraction complexity

The output from this kind of analysis is often illuminating. In one recent engagement, an agent identified that the organization had no fewer than twelve different approaches to HTTP client instantiation across their service fleet. Some used raw HttpClient (with all the socket exhaustion problems that entails). Some used IHttpClientFactory correctly. Some used it incorrectly. A few had hand-rolled retry logic. Others used Polly but configured it differently. One particularly creative implementation had a static HttpClient wrapped in a lock statement "for thread safety."

None of this was visible from any single repository. It only became apparent when you looked across the portfolio. And that's exactly the kind of analysis that agents excel at.

The Enumeration Phase

Once you've identified candidate concerns, the next step is enumeration: building a comprehensive inventory of where each concern appears and how it's currently implemented. This is tedious work for humans but trivial for agents.

For the HTTP client example, the enumeration might look like:

HTTP Client Implementations Inventory:

1. ServiceA/Infrastructure/HttpClientWrapper.cs
   - Pattern: Static HttpClient with manual DNS refresh
   - Retry logic: None
   - Timeout: 30 seconds (hardcoded)
   - Dependencies: None

2. ServiceB/Clients/ExternalApiClient.cs
   - Pattern: IHttpClientFactory via constructor injection
   - Retry logic: Polly with 3 retries, exponential backoff
   - Timeout: Configured via appsettings.json
   - Dependencies: Polly, Microsoft.Extensions.Http

3. ServiceC/Utilities/ApiHelper.cs
   - Pattern: New HttpClient per request (!)
   - Retry logic: Manual try-catch with Thread.Sleep
   - Timeout: 100 seconds (default)
   - Dependencies: None

[... and so on for each occurrence ...]

This inventory becomes the foundation for the next phase. You can't plan an extraction without knowing what you're extracting from.

Categorizing by Extraction Complexity

Not all cross-cutting concerns are equally amenable to extraction. Some are straightforward (everyone's doing roughly the same thing, just in different places). Others are deeply entangled with business logic or have subtle behavioral differences that must be preserved.

I typically categorize concerns into three buckets:

Low complexity: The implementations are nearly identical, differ only in configuration, and have no dependencies on application-specific types. These can often be extracted in a day or two.

Medium complexity: The implementations share a common core but have legitimate variations that need to be accommodated through configuration, extension points, or strategy patterns. These might take a week or two to extract properly.

High complexity: The implementations have diverged significantly, are entangled with business logic, or have undocumented behavioral quirks that applications depend on. These require careful analysis and potentially phased migration strategies.

Agents can help with this categorization, but human judgment is essential. An agent might see two implementations that look different and assume high complexity, when in reality one is just a worse version of the other that can be safely replaced. Or it might see two implementations that look similar but miss subtle semantic differences that matter enormously in production.

Building the Concern Registry

The output of this phase should be a structured registry of identified concerns, something that can be referenced throughout the extraction effort and maintained going forward. I like to keep these as markdown files in a dedicated repository:

# Cross-Cutting Concerns Registry

## HTTP Client Management
- **Status**: Identified, awaiting prioritization
- **Complexity**: Medium
- **Occurrences**: 12 services
- **Primary variations**: Retry policies, timeout configurations, authentication handling
- **Proposed solution**: Shared library with configurable policies
- **Estimated effort**: 2 weeks extraction, 4 weeks migration

## Structured Logging
- **Status**: In progress
- **Complexity**: Low
- **Occurrences**: 23 services
- **Primary variations**: Log format, correlation ID propagation
- **Proposed solution**: Thin wrapper over Serilog with standard enrichers
- **Estimated effort**: 1 week extraction, 2 weeks migration

[... additional concerns ...]

This registry serves multiple purposes. It documents what you've found. It helps prioritize extraction efforts. It provides a reference for developers who might otherwise duplicate these concerns yet again. And it becomes the basis for the architectural decision records you'll create in the planning phase.

Reporting and Analysis

Once you've identified and enumerated your cross-cutting concerns, the next challenge is communicating what you've found. This is where many technical initiatives die: not because the analysis was wrong, but because it never made it out of the developer's head and into a form that others could act on.

The Architecture Decision Record

For each significant cross-cutting concern you plan to address, I strongly recommend creating an Architecture Decision Record (ADR). These documents serve as both analysis and proposal, capturing the current state, the problem it causes, the proposed solution, and the trade-offs involved.

Agents are surprisingly good at drafting ADRs, particularly the background and analysis sections. They can synthesize the enumeration data you gathered earlier into a coherent narrative. The key is to review and refine their output, adding the organizational context and political considerations that agents can't know.

A typical ADR structure might look like:

# ADR-007: Standardize HTTP Client Management

## Status
Proposed

## Context
Our service portfolio currently contains 12 different approaches to HTTP
client management. This inconsistency has led to:

- Production incidents due to socket exhaustion (ServiceC, ServiceF)
- Inconsistent retry behavior causing cascading failures
- Security vulnerabilities from improper certificate validation
- Developer confusion and duplicated effort

Analysis of the current implementations reveals three main categories:
[detailed breakdown follows]

## Decision
We will create a shared library (`Company.Http.Resilience`) that provides:

1. Pre-configured HttpClient instances via IHttpClientFactory
2. Standard retry policies with configurable parameters
3. Circuit breaker integration
4. Consistent timeout handling
5. Structured logging of HTTP operations
6. Health check integration

## Consequences

### Positive
- Consistent behavior across all services
- Reduced incident rate from HTTP-related issues
- Faster onboarding for new developers
- Single place to update security configurations

### Negative
- Migration effort required for existing services
- Learning curve for teams unfamiliar with new patterns
- Potential for breaking changes if not carefully managed

### Neutral
- Requires ongoing maintenance of shared library
- Need to establish governance for library updates

## Migration Strategy
[phased approach details]

Generating Reports for Different Audiences

One of the underappreciated aspects of this work is that different stakeholders need different views of the same information. A detailed technical analysis is great for the architecture team, but it's not what you show in a sprint planning meeting or a budget request.

Agents can help generate multiple views from the same underlying data:

Executive summary (for leadership):

We've identified 12 inconsistent HTTP client implementations across our
services. This inconsistency contributed to 3 production incidents last
quarter and consumes approximately 40 developer-hours per month in
debugging and maintenance. A 2-week investment to create a standardized
library would eliminate this overhead and reduce incident risk.

Technical summary (for architecture review):

Cross-cutting concern: HTTP client management
Current state: 12 implementations, 4 distinct patterns
Risk level: High (socket exhaustion, retry storms)
Proposed solution: Shared library with IHttpClientFactory, Polly policies
Effort estimate: 80 hours extraction, 160 hours migration
Dependencies: Microsoft.Extensions.Http, Polly

Developer guide (for implementation teams):

# Migrating to Company.Http.Resilience

## Why are we doing this?
[brief context]

## What changes for me?
[concrete before/after examples]

## How do I migrate?
[step-by-step instructions]

## What if I need custom behavior?
[extension points and configuration options]

The Analysis Artifact Pipeline

I've found it useful to establish a standard pipeline for producing these artifacts. When a new cross-cutting concern is identified, the pipeline kicks in:

Raw enumeration (agent-generated): List of all occurrences with code snippets
Categorized analysis (agent-generated, human-reviewed): Complexity assessment, variation analysis
ADR draft (agent-generated, human-refined): Formal decision record
Executive summary (agent-generated from ADR): One-page overview
Migration guide (agent-generated after solution is built): Developer-facing documentation

Each artifact builds on the previous ones, and the agent can be prompted to maintain consistency across them. If the ADR changes, the executive summary and migration guide should be regenerated to reflect those changes.

Maintaining the Paper Trail

Documentation has a half-life. The moment you finish writing it, it starts decaying. Requirements change, implementations evolve, and that carefully crafted ADR becomes a historical curiosity rather than a living reference.

This is where the combination of agents and good tooling pays dividends. If your analysis artifacts are stored in version control (and they should be), you can periodically prompt an agent to review them against the current codebase:

Review ADR-007 against the current state of our HTTP client implementations.
Identify any drift between the documented decision and actual implementation.
Flag any new services that haven't adopted the standard library.
Suggest updates to the ADR if the decision should be revised.

This kind of maintenance review is exactly the sort of tedious, important work that humans tend to skip and agents can do reliably. Schedule it quarterly, tie it to your release cycles, or trigger it whenever significant changes are merged to the shared libraries.

Planning the Solution

This is where human judgment becomes essential. Agents can identify patterns, enumerate occurrences, and draft documentation, but they cannot make architectural decisions. They don't understand your organization's priorities, your team's capabilities, your deployment constraints, or the political landscape that determines what solutions are actually viable.

Planning is collaborative, but the human must drive.

Defining Boundaries

The first planning decision is scope: what exactly are you extracting, and what are you leaving behind?

This sounds simple, but it's where most extraction efforts go wrong. The temptation is to solve everything at once. You start with "let's standardize HTTP client management" and end up with "let's create a comprehensive platform SDK that handles HTTP, logging, configuration, caching, authentication, and messaging." Six months later, you've built a framework that nobody wants to adopt because it's too opinionated, too complex, and too different from what teams are currently using.

The antidote is aggressive scoping. For each cross-cutting concern, define:

What's in scope:

The specific functionality being extracted
The configuration surface area
The extension points (if any)
The test coverage requirements

What's explicitly out of scope:

Related functionality that could be added later
Integrations with other concerns
Business-specific customizations
Anything that would delay the initial release

Write these boundaries down. Put them in the ADR. Refer back to them when you (or your agent) start gold-plating.

Designing the Interface Contract

Before any implementation begins, you need to define the contract that consuming applications will depend on. This is the most important artifact you'll produce, because it's the hardest to change later.

For a shared library, the contract includes:

Public types (interfaces, classes, records, enums)
Configuration schema (options classes, configuration sections)
Behavioral guarantees (what happens on failure, what gets logged, what metrics are emitted)
Dependencies (what NuGet packages are required, what framework versions are supported)

I typically start by writing the consuming code first. Before any implementation exists, write how you want developers to use the library. This outside-in approach ensures that the interface is designed for the consumer, not for the implementer. It's the same philosophy that drives behavior-driven development: start with what you want to observe, then work backward to what you need to build.

Fluent Over Nested

When designing interfaces, I have a strong bias toward fluent APIs. A fluent API chains method calls, reads left-to-right (or top-to-bottom), and minimizes the cognitive load required to understand what's happening.

Compare these two approaches to configuring an HTTP client:

// Nested/Constructor-heavy approach
var client = new ResilientHttpClient(
    new HttpClientOptions(
        baseAddress: "https://api.example.com",
        timeout: TimeSpan.FromSeconds(30),
        retryPolicy: new RetryPolicy(
            maxRetries: 3,
            backoffType: BackoffType.Exponential,
            initialDelay: TimeSpan.FromMilliseconds(100)
        ),
        circuitBreaker: new CircuitBreakerOptions(
            failureThreshold: 5,
            samplingDuration: TimeSpan.FromMinutes(1),
            breakDuration: TimeSpan.FromSeconds(30)
        )
    )
);

// Fluent approach
var client = ResilientHttpClient
    .Create("https://api.example.com")
    .WithTimeout(TimeSpan.FromSeconds(30))
    .WithRetry(retry => retry
        .MaxAttempts(3)
        .ExponentialBackoff()
        .InitialDelay(TimeSpan.FromMilliseconds(100)))
    .WithCircuitBreaker(breaker => breaker
        .TripAfter(5).FailuresIn(TimeSpan.FromMinutes(1))
        .StayOpenFor(TimeSpan.FromSeconds(30)))
    .Build();

The fluent version is longer in line count but dramatically easier to read. Each configuration concern is isolated to its own chain. You can understand the retry policy without mentally parsing nested constructor arguments. The indentation is shallow and consistent.

This matters for agent-assisted development in two ways. First, when you ask an agent to implement a fluent API, it's forced to think about each configuration concern in isolation. It can't hide complexity in nested constructors. Second, when you ask an agent to use a fluent API, the resulting code is more likely to be correct because each step is self-documenting.

I've built entire libraries around this philosophy. PatternKit provides fluent implementations of Gang of Four patterns precisely because the traditional examples are unnecessarily verbose and nested. TinyBDD uses a fluent Given/When/Then syntax because test scenarios should read like specifications, not like procedural code.

When planning your extracted libraries, default to fluent. Your future self (and your agents) will thank you.

Design for Validation

But there's another dimension to consider: design for validation. Every interface you create should be testable. Every behavior should be observable. Every configuration should be verifiable. If you can't write a test that proves the component works correctly, your interface is wrong.

This is especially important when agents will be involved in the implementation. Remember: you want to validate tools, not trust decisions. That means your interfaces need to expose seams where validation can occur. Opaque interfaces that hide all internal state make it impossible to verify correct behavior. Transparent interfaces with clear inputs, outputs, and observable side effects make validation straightforward.

// This is what we WANT the consuming code to look like

public class MyService
{
    private readonly IResilientHttpClient _http;

    public MyService(IResilientHttpClient http)
    {
        _http = http;
    }

    public async Task<CustomerData> GetCustomerAsync(string customerId)
    {
        // Simple case: just make the call, resilience is handled for us
        return await _http.GetAsync<CustomerData>($"/customers/{customerId}");
    }

    public async Task<OrderResult> PlaceOrderAsync(Order order)
    {
        // Custom configuration for this specific call
        var options = new HttpCallOptions
        {
            Timeout = TimeSpan.FromSeconds(60),
            RetryPolicy = RetryPolicy.None  // Orders shouldn't auto-retry
        };

        return await _http.PostAsync<OrderResult>("/orders", order, options);
    }
}

And the registration:

// In Startup or Program.cs
services.AddResilientHttpClient(options =>
{
    options.BaseAddress = configuration["ApiBaseUrl"];
    options.DefaultTimeout = TimeSpan.FromSeconds(30);
    options.RetryPolicy = new RetryPolicyOptions
    {
        MaxRetries = 3,
        BackoffType = BackoffType.Exponential
    };
    options.CircuitBreaker = new CircuitBreakerOptions
    {
        FailureThreshold = 5,
        SamplingDuration = TimeSpan.FromMinutes(1),
        BreakDuration = TimeSpan.FromSeconds(30)
    };
});

This "outside-in" approach ensures that the interface is designed for the consumer, not for the implementer. It's the same philosophy that drives behavior-driven development: start with what you want to observe, then work backward to what you need to build.

Leveraging Agents for Interface Exploration

While the human defines the desired interface, agents can be invaluable for exploring the design space. Give them the proposed interface and ask:

Review this proposed interface for a resilient HTTP client library.
Consider:
- Usability: Is this intuitive for developers to use?
- Flexibility: Can it accommodate the variations we found in our analysis?
- Testability: Can consuming code easily mock or stub this?
- Consistency: Does it follow .NET conventions and patterns?
- Evolution: Can we extend this without breaking changes?

Identify potential issues and suggest alternatives.

The agent might surface considerations you hadn't thought of:

"The RetryPolicy.None option might be confusing; consider RetryPolicy.Disabled for clarity."
"You're using a concrete HttpCallOptions class; an interface would improve testability."
"The circuit breaker configuration is complex; consider providing named presets like CircuitBreaker.Aggressive and CircuitBreaker.Conservative."

Not all suggestions will be good, but the exploration is valuable. It's like having a code review before the code exists.

Creating the Behavior Specification

Once the interface is defined, the next step is specifying its behavior. This is where TinyBDD (or your BDD framework of choice) shines. Write the scenarios that define what the library must do:

[Feature("Resilient HTTP Client")]
public class ResilientHttpClientScenarios : TinyBddXunitBase
{
    [Scenario("Successful request returns deserialized response")]
    [Fact]
    public async Task SuccessfulRequest()
    {
        await Given("a configured resilient HTTP client", () =>
                CreateTestClient(respondWith: new CustomerData { Id = "123", Name = "Test" }))
            .When("making a GET request", client =>
                client.GetAsync<CustomerData>("/customers/123"))
            .Then("the response is deserialized correctly", customer =>
                customer.Id == "123" && customer.Name == "Test")
            .AssertPassed();
    }

    [Scenario("Transient failure triggers retry")]
    [Fact]
    public async Task TransientFailureRetry()
    {
        await Given("a client configured with 3 retries", () =>
                CreateTestClient(failTimes: 2, thenSucceed: true))
            .When("making a request that fails twice then succeeds", client =>
                client.GetAsync<CustomerData>("/customers/123"))
            .Then("the request ultimately succeeds", customer =>
                customer != null)
            .And("exactly 3 attempts were made", () =>
                GetAttemptCount() == 3)
            .AssertPassed();
    }

    [Scenario("Circuit breaker opens after threshold")]
    [Fact]
    public async Task CircuitBreakerOpens()
    {
        await Given("a client with circuit breaker (threshold: 3 failures)", () =>
                CreateTestClient(alwaysFail: true, circuitBreakerThreshold: 3))
            .When("making 5 failing requests", async client =>
            {
                for (int i = 0; i < 5; i++)
                {
                    try { await client.GetAsync<CustomerData>("/customers/123"); }
                    catch { /* expected */ }
                }
                return client;
            })
            .Then("the circuit breaker is open", client =>
                client.IsCircuitBreakerOpen)
            .And("later requests fail fast without attempting", async client =>
            {
                var sw = Stopwatch.StartNew();
                try { await client.GetAsync<CustomerData>("/customers/123"); }
                catch { /* expected */ }
                return sw.ElapsedMilliseconds < 100;  // Should fail immediately
            })
            .AssertPassed();
    }
}

These scenarios become the acceptance criteria for your implementation. They define "done." They're the contract between you (the architect) and whoever implements the library (possibly an agent, possibly a developer, possibly you at 2 AM after too much coffee).

The Planning Artifact

The output of the planning phase should be a comprehensive specification that can be handed to an implementer (human or otherwise):

Interface definitions (the public API surface)
Behavior scenarios (the BDD specs that define correctness)
Configuration schema (what options are available and what they do)
Dependency list (what packages are required)
Non-functional requirements (performance targets, compatibility requirements)
Out-of-scope list (what this version explicitly doesn't do)

With these artifacts in hand, the implementation phase becomes almost mechanical. The creative work is done. The decisions are made. Now it's just a matter of making the scenarios pass.

Building Domain-Specific Solutions

With a clear specification in hand, implementation becomes the most straightforward phase of the entire process. This is where agents really earn their keep. They're not making architectural decisions (those are already made). They're not interpreting vague requirements (those are already specified as scenarios). They're simply writing code to make tests pass.

The Implementation Loop

The implementation workflow follows a tight loop:

Give the agent the interface definition and one or two scenarios
Have it produce an implementation
Run the scenarios
If they fail, provide the failure output and iterate
If they pass, move to the next batch of scenarios
Repeat until all scenarios are green

This is not unlike test-driven development, except the agent is doing most of the typing. You're still driving the process, reviewing the output, and making judgment calls when the agent gets stuck or produces something questionable.

Guiding Toward Flat, Functional Implementations

When prompting for implementations, I explicitly request flat, functional code. This isn't just stylistic preference; it directly impacts the quality of agent-generated code.

Agents have a tendency to produce deeply nested, imperative code when left to their defaults. They've been trained on millions of lines of code, and unfortunately, a lot of that code is nested spaghetti. If you don't specify otherwise, you'll get if statements inside try blocks inside foreach loops inside while conditions.

Counter this by being explicit in your prompts:

Implement the retry logic for IResilientHttpClient.

Style requirements:
- Prefer pure functions over stateful methods
- Use early returns to avoid nesting
- Chain operations rather than nesting them
- Each method should do one thing
- Avoid mutable state where possible
- Use pattern matching over if/else chains

Example of the style I want:
[paste example of flat, functional code from your codebase]

The difference in output quality is stark. With explicit style guidance, you get code like:

public async Task<T> ExecuteWithRetryAsync<T>(
    Func<Task<T>> operation,
    RetryPolicy policy,
    CancellationToken ct = default)
{
    return await policy.Attempts
        .Select(attempt => TryExecute(operation, attempt, ct))
        .FirstSuccessOrThrowAggregate();
}

private async Task<Result<T>> TryExecute<T>(
    Func<Task<T>> operation,
    int attempt,
    CancellationToken ct)
{
    try
    {
        var result = await operation();
        return Result.Success(result);
    }
    catch (Exception ex) when (IsTransient(ex))
    {
        await DelayForAttempt(attempt, ct);
        return Result.Failure<T>(ex);
    }
}

Without style guidance, you get:

public async Task<T> ExecuteWithRetryAsync<T>(
    Func<Task<T>> operation,
    RetryPolicy policy,
    CancellationToken ct = default)
{
    int attempts = 0;
    List<Exception> exceptions = new List<Exception>();

    while (attempts < policy.MaxAttempts)
    {
        try
        {
            return await operation();
        }
        catch (Exception ex)
        {
            if (IsTransient(ex))
            {
                exceptions.Add(ex);
                attempts++;
                if (attempts < policy.MaxAttempts)
                {
                    await Task.Delay(CalculateDelay(attempts), ct);
                }
            }
            else
            {
                throw;
            }
        }
    }

    throw new AggregateException(exceptions);
}

Both might work, but the first is easier to test, easier to modify, and easier to reason about. The functional version has clear data flow. Each function transforms input to output. The imperative version has hidden state (attempts, exceptions), multiple exit points, and nested control flow.

A typical prompting session might look like:

Implement the IResilientHttpClient interface according to this specification.
Start with the basic request/response flow - don't worry about retry logic yet.

Interface:
[paste interface definition]

Scenario to satisfy:
[paste the "Successful request returns deserialized response" scenario]

Constraints:
- Use System.Net.Http.HttpClient internally via IHttpClientFactory
- Use System.Text.Json for serialization
- Follow .NET naming conventions
- Include XML documentation comments

The agent produces an implementation. You run the scenario. It passes (or doesn't). You iterate.

Handling Implementation Complexity

Not all scenarios are equally straightforward. The basic happy path is usually trivial. The edge cases are where implementations get interesting.

For complex scenarios like circuit breaker behavior, I've found it helpful to break the implementation into phases:

Phase 1: Core flow

Basic request/response
Serialization/deserialization
Error handling

Phase 2: Retry logic

Configurable retry policies
Exponential backoff
Jitter

Phase 3: Circuit breaker

Failure tracking
State transitions (closed -> open -> half-open)
Recovery logic

Phase 4: Observability

Structured logging
Metrics emission
Correlation ID propagation

Each phase has its own scenarios, and each phase builds on the previous one. The agent doesn't need to solve everything at once. It just needs to make the current phase's scenarios pass without breaking the previous phases.

Code Review and Refinement

Agent-generated code needs review. Always. Without exception.

The good news is that reviewing code is much faster than writing it. And because you have comprehensive scenarios, you can focus your review on concerns that tests don't catch:

Style and convention: Does this match your existing codebase?
Performance: Are there obvious inefficiencies?
Security: Are there potential vulnerabilities?
Maintainability: Will future developers understand this?
Edge cases: Are there scenarios we didn't think to specify?

I typically do a first pass looking for obvious issues, then run the code through any static analysis tools we use (Roslyn analyzers, SonarQube, etc.), then do a deeper read of any code that handles security or concurrency.

The agent can help with refinement too:

Review this implementation for potential issues:
[paste code]

Specifically check for:
- Thread safety concerns
- Resource disposal issues
- Potential for null reference exceptions
- Adherence to .NET best practices

Suggest improvements but don't rewrite the entire thing.

Source Generators: The Ultimate Validation Target

This is where the "tools, not decisions" philosophy really shines. Rather than having an agent write your boilerplate code directly, have it write a source generator that produces the boilerplate.

Consider a common scenario: you have fifty entities that all need repository interfaces, implementations, and registration code. The traditional approach (even with agents) is to generate each one individually, review each one, and hope they're all consistent. The better approach is to have the agent build a source generator that examines your entities and emits the correct code for all of them.

The prompt might look like:

Create a C# source generator that:
1. Finds all classes decorated with [Repository]
2. Generates an IXxxRepository interface with standard CRUD methods
3. Generates an XxxRepository implementation using our base class
4. Generates extension methods for DI registration

Conventions to follow:
- Interface goes in Abstractions namespace
- Implementation goes in Infrastructure namespace
- Use async/await throughout
- Include XML documentation

Here's an example of what the generated code should look like:
[paste example of desired output]

The agent produces a source generator. You add it to a test project with a few decorated classes. You inspect the generated code. You verify it compiles, follows your conventions, and works correctly. You write tests against the generator itself:

[Fact]
public void Generator_Creates_Interface_For_Decorated_Class()
{
    var source = @"
        [Repository]
        public class Customer { public int Id { get; set; } }
    ";

    var generated = RunGenerator(source);

    generated.ShouldContain("public interface ICustomerRepository");
    generated.ShouldContain("Task<Customer?> GetByIdAsync(int id)");
}

[Fact]
public void Generator_Follows_Namespace_Conventions()
{
    var source = @"
        namespace MyApp.Domain
        {
            [Repository]
            public class Order { }
        }
    ";

    var generated = RunGenerator(source);

    generated.ShouldContain("namespace MyApp.Abstractions");
    generated.ShouldContain("namespace MyApp.Infrastructure");
}

Now you've validated the tool. The generator is tested. It produces correct code for your test cases. And when you add your fifty entities, you don't need to review fifty repositories. You need to verify that your entities are properly decorated and let the (validated) generator do its work.

This is a fundamentally different relationship with AI assistance. You're not trusting the agent to write correct code for each entity. You're trusting yourself to validate a tool that the agent helped you build. The agent's contribution is leverage (building the generator faster than you could), not judgment (deciding what the repositories should look like).

The same pattern applies to:

Analyzers: Have the agent build Roslyn analyzers that enforce your conventions, rather than trusting it to follow them
Scaffolding tools: Build CLI tools that generate project structures, rather than having the agent create each project
Migration generators: Build tools that examine schema differences and emit migrations, rather than hand-writing each one
Documentation generators: Build tools that extract XML docs and produce markdown, rather than writing docs manually

Each of these transforms "trust the agent's output" into "validate the agent's tool." It's the difference between hiring someone to do a task and hiring someone to build a machine that does the task. The machine can be tested. The machine is consistent. The machine doesn't have bad days.

Testing Beyond Scenarios

BDD scenarios define the behavioral contract, but they're not the only tests you need. Implementation-level unit tests, integration tests with real dependencies, and performance tests all have their place.

For a shared library, I typically want:

Scenario tests (BDD): Define the behavioral contract from the consumer's perspective

Unit tests: Cover implementation details that scenarios don't reach (edge cases in internal methods, etc.)

Integration tests: Verify behavior against real dependencies (actual HTTP servers, actual circuit breakers under load)

Performance tests: Ensure the implementation doesn't introduce unacceptable overhead

Agents can generate all of these. The scenario tests exist by definition (you wrote them in the planning phase). Unit tests can be generated from the implementation:

Generate unit tests for the RetryPolicy class.
Achieve >90% code coverage.
Focus on edge cases: zero retries, maximum retries, invalid configurations.
Use xUnit and FluentAssertions.

Integration and performance tests usually require more human guidance because they depend on your specific infrastructure, but agents can still do the heavy lifting once you provide the context.

Packaging and Publishing

Once the implementation is complete and all tests pass, the library needs to be packaged for consumption. This typically means:

NuGet package configuration (.csproj settings, .nuspec if needed)
Version management (semantic versioning, changelog generation)
CI/CD pipeline (build, test, pack, publish)
Package documentation (README, API docs)

Most of this is boilerplate that agents can generate from templates. The key decisions (version number, release notes, breaking change warnings) require human judgment, but the mechanical work doesn't.

Generate the NuGet package configuration for Company.Http.Resilience.
Include:
- Package metadata (description, authors, license, repository URL)
- Dependency specifications
- README inclusion
- Source Link configuration for debugging

Follow the conventions used in our existing packages:
[paste example .csproj]

The Implementation Artifact

The output of the build phase is a functioning library with:

Source code that implements the specified interface
Passing scenarios that prove behavioral correctness
Unit tests that cover implementation details
Integration tests that verify real-world behavior
Package configuration ready for publishing
Documentation for consumers

At this point, the concern is extracted. It exists as a standalone, versioned, tested artifact. The remaining work is migrating existing applications to use it and maintaining it going forward.

Maintenance and Evolution

This is the phase that everyone forgets about and nobody budgets for. The library is built. The first few applications have migrated. The project is declared a success and the team moves on to the next initiative.

Six months later, someone files a bug report. A year later, a dependency releases a breaking change. Two years later, a new developer asks why the library does something a certain way and nobody remembers.

Maintenance is not glamorous, but it's where the investment in good architecture pays dividends (or doesn't).

The Maintenance Mindset

The goal of maintenance is not to keep the library frozen in amber. It's to keep it useful, secure, and aligned with the evolving needs of its consumers. This requires:

Proactive work: Dependency updates, security patches, performance improvements

Reactive work: Bug fixes, feature requests, compatibility updates

Communication: Release notes, migration guides, deprecation warnings

Agents can help with all of these, but they need context about what's changed and what matters.

Dependency Management

Every library has dependencies, and dependencies evolve. At minimum, you need to:

Track dependency updates (major, minor, patch releases)
Assess the impact of updates (breaking changes, new features, security fixes)
Apply updates on a reasonable cadence
Test thoroughly before releasing

I use agents to help with dependency triage:

Review the following dependency updates for Company.Http.Resilience:

- Microsoft.Extensions.Http: 8.0.0 -> 8.0.1 (patch)
- Polly: 8.2.0 -> 8.3.0 (minor)
- System.Text.Json: 8.0.0 -> 9.0.0 (major)

For each update:
1. Summarize what changed (check release notes)
2. Assess breaking change risk
3. Recommend whether to update now, later, or skip
4. Note any code changes required in our library

The agent's assessment isn't final, but it saves hours of manual research. For major version bumps especially, having a summary of breaking changes before diving into the release notes is invaluable.

Handling Feature Requests

Consumers will want things your library doesn't do. This is healthy. It means people are using it. But not every feature request should be implemented.

For each request, ask:

Is it within scope? Does this align with the library's purpose, or should it be a separate concern?
How many consumers need it? Is this a common need or a one-off?
Can it be done without breaking changes? Will existing consumers be affected?
What's the maintenance burden? Will this make the library harder to understand and maintain?

Agents can help evaluate requests against these criteria:

Evaluate this feature request for Company.Http.Resilience:

Request: Add support for request/response caching

Consider:
- Our stated scope: HTTP client resilience (retry, circuit breaker, timeout)
- Caching is related but distinct from resilience
- Adding caching would increase complexity significantly
- Caching has its own configuration concerns (TTL, invalidation, storage)

Recommendation: Accept, reject, or defer? Justify.

The recommendation might be: "Defer. Caching is related to HTTP concerns but orthogonal to resilience. Consider a separate Company.Http.Caching library that composes with this one. If multiple consumers request it, prioritize the separate library."

Version Evolution

Libraries evolve through versions. Semantic versioning provides the framework (major.minor.patch), but the decisions about what goes into each version are human judgment calls.

I maintain a version roadmap for each shared library:

# Company.Http.Resilience Version Roadmap

## Current: 1.2.0
- Retry with exponential backoff
- Circuit breaker
- Configurable timeouts
- Structured logging

## Planned: 1.3.0 (Q2 2026)
- Request hedging (speculative execution)
- Enhanced metrics (histograms, percentiles)
- .NET 9 support

## Planned: 2.0.0 (Q4 2026)
- Breaking: Simplified configuration API
- Breaking: Remove deprecated methods from 1.x
- New: Native AOT support
- New: gRPC resilience (separate package)

## Backlog (unprioritized)
- Request caching (may be separate library)
- Custom serializers
- Request signing

This roadmap is a living document. It changes as priorities shift and new information emerges. But having it written down prevents the library from drifting aimlessly and helps consumers plan their own upgrades.

Documentation Maintenance

Documentation decays. APIs change but examples don't get updated. New features ship without corresponding docs. Deprecated features linger in the guides long after they've been removed.

Periodic documentation audits are essential:

Audit the documentation for Company.Http.Resilience:

1. Compare public API surface to documented features
2. Identify undocumented public members
3. Identify documented features that no longer exist
4. Check that code examples compile against current version
5. Verify links are not broken

Report discrepancies and suggest fixes.

This is exactly the kind of tedious, important work that agents excel at. They're patient enough to check every example and thorough enough to catch what humans skip.

The Maintenance Rhythm

Rather than treating maintenance as ad-hoc work that happens when things break, establish a rhythm:

Weekly: Dependency update review (automated alerts, manual triage)

Monthly: Feature request review (batch similar requests, make decisions)

Quarterly: Documentation audit, roadmap review

Yearly: Major version planning, breaking change assessment

This rhythm can be partially automated. Set up alerts for dependency updates. Create recurring calendar items for reviews. Use agents to generate the reports that feed into each review.

The goal is to make maintenance a sustainable, predictable activity rather than a crisis response.

Conclusion

When I started this journey at my new company, staring down hundreds of codebases and thousands of interwoven concerns, I didn't have a grand plan. A laptop. A curiosity about what AI tools could actually do in practice. An allergy to doing the same thing twice. That's what I had.

What emerged from that combination is what I've been calling "vibe engineering." Still somewhat tongue-in-cheek, but the name has stuck. It's not a methodology with certification programs and expensive consultants. It's a way of working that recognizes both the immense capability and the critical limitations of AI agents.

The capability is real. Agents can read code faster than any human. They identify patterns across codebases that would take weeks to discover manually. They generate documentation, draft implementations, produce test suites at a pace that would have seemed like science fiction five years ago.

The limitations are equally real. Agents don't understand your organization. They don't know why decisions were made. They can't navigate the political landscape that determines what solutions actually get adopted. They lack the judgment to know when "technically correct" isn't good enough.

Here's the key insight: these capabilities and limitations are complementary.

Agents excel at exactly the things humans find tedious. Reading vast amounts of code. Maintaining documentation. Generating boilerplate. Checking consistency. Humans excel at exactly the things agents struggle with. Understanding context. Making judgment calls. Navigating organizational dynamics. Designing for the long term.

Vibe engineering is about creating the right handoff points. Humans define scope, make architectural decisions, review outputs. Agents do the heavy lifting of analysis, generation, and maintenance. The "vibe" is the context, constraints, and creative latitude that make this collaboration productive.

And part of that vibe is aesthetic.

I've come to believe that the code style you demand directly impacts the quality of agent collaboration. Flat beats nested. Declarative beats imperative. Fluent beats verbose. Pure functions beat stateful methods. These aren't just preferences. They're force multipliers. Code written in this style is easier to specify, easier to generate, easier to test, and easier to maintain.

When everything chains cleanly. When each step is a transformation rather than a mutation. When the code reads like a specification of what should happen rather than instructions for how to make it happen. That's when you've created an environment where both humans and agents can do their best work.

What I've Learned

Several months into this approach, a few lessons have crystallized.

Start small. The temptation is to extract everything at once. Build the comprehensive platform SDK that solves all problems. Resist this. Extract one concern at a time. Make it work. Get it adopted. Then move to the next.

Build tools, not outputs. This might be the most important lesson. When you have an agent write code directly, you're trusting its judgment for that specific case. When you have an agent build a source generator, analyzer, or scaffolding tool, you can validate the tool once and trust its output forever. The difference between "agent writes fifty repositories" and "agent writes a generator that produces fifty repositories" is the difference between reviewing fifty files and validating one tool. Always prefer the latter.

Demand flat, declarative code. Agents default to nested, imperative spaghetti. That's what most of their training data looks like. Be explicit about wanting flat, functional, fluent code. Provide examples. The quality difference is enormous. Declarative code is inherently easier to validate because each step is a discrete, testable transformation.

Invest in specifications. The time spent defining interfaces and writing scenarios is not overhead. It's the work. A clear specification makes implementation almost mechanical. Doesn't matter if it's done by an agent, a junior developer, or yourself at 2 AM.

Trust but verify. Agent-generated code needs review. Always. Scenarios provide a safety net for behavioral correctness, but style, security, and maintainability require human eyes. This is doubly true for tools and generators, where a bug gets multiplied across every output.

Design for validation. Every interface should be testable. Every behavior should be observable. If you can't write a test that proves the component works correctly, your interface is wrong. This isn't just good practice. It's essential when agents are involved, because validation is how you transform "trust" into "verify."

Prefer fluent APIs. Fluent interfaces read like specifications. They're self-documenting. They force separation of concerns. They're easier for both humans and agents to use correctly. When in doubt, make it chainable.

Maintain the paper trail. ADRs, inventories, roadmaps, documentation. These aren't bureaucratic overhead. They're institutional memory that keeps work coherent over time. They're also the context that makes future agent interactions productive.

Establish rhythms. Maintenance is not a crisis response. It's a sustainable practice. Weekly dependency reviews. Monthly feature triage. Quarterly audits. Make it routine and it becomes manageable.

The Bigger Picture

I've focused this essay on cross-cutting concerns because they're the Goldilocks zone for human-agent collaboration. Complex enough to be meaningful. Bounded enough to be tractable. Infrastructure-focused enough that deep business context isn't required.

But the principles extend beyond infrastructure. Any well-scoped, clearly specified problem can benefit from this approach. The key is knowing when to reach for agent assistance and when to do the work yourself.

The tools will continue to evolve. Rapidly. The boundary will shift. Tasks requiring heavy human involvement today will become more automatable. New categories of work will emerge that we can't yet imagine. The developers who thrive will be those who can fluidly navigate this shifting boundary, leveraging agents where they're effective and applying human judgment where it's essential.

For now, though, there's plenty of spaghetti to untangle. Plenty of fungal colonies to dissect. Plenty of cross-cutting concerns hiding in plain sight, waiting to be identified, specified, extracted, and maintained.

And I've got an agent ready to help.

This is part one of what I expect to be an ongoing series on AI-assisted software engineering. Future posts will dive deeper into specific techniques, tooling, and real-world case studies. If you want to follow along, the best place is probably my blog at jerrettdavis.com or wherever you found this post.

All code examples in this post are illustrative. The specific implementations would vary based on your stack, constraints, and preferences. The principles, however, are stack-agnostic.

Announcing TinyBDD: Fluent, Executable Scenarios for .NET

Jerrett Davis — Sat, 27 Dec 2025 19:29:16 +0000

This article was originally published on my blog.

Announcing TinyBDD: Fluent, Executable Scenarios for .NET

👉 GitHub · NuGet · Docs

What if the shortest path from "we need this" to "it works in prod" was just a single fluent line of code?

TinyBDD is my attempt to make that path real. It's a lightweight .NET library that lets you write tests in a fluent, Gherkin-ish style—tests that read like acceptance criteria but execute like unit tests. The goal is not ceremony, but clarity: a shared, human-parsable DSL that can span from domain rules to browser automation without losing intent.

This post is the practical follow-up to my earlier essay on BDD. There, I dug into the why. Here, we'll focus on the how: how to go from acceptance criteria to running tests in minutes, how to use Given/When/Then to model even the smallest units, how to orchestrate full end-to-end flows with Playwright, and how writing this way naturally nudges your architecture toward SOLID and composable design.

From acceptance criteria to running tests in minutes

Every team has seen a story like this written in Jira or Confluence:


Scenario: Gold member gets free shipping
Given the customer is a "gold" member
And they have a cart totaling $12.00
When they checkout with standard shipping
Then the shipping cost is $0.00
And the order total is $12.00

With TinyBDD, you don't need separate .feature files unless you want them. You can capture that same intent directly in your test framework, keeping the semantics without the tooling overhead:

await Given("a gold customer with a $12 cart", () => new Cart(Customer.Gold(), 12.00m))
     .When("they choose standard shipping", cart => cart.Checkout(Shipping.Standard))
     .Then("shipping is free", order => order.ShippingTotal == 0.00m)             // Pass/Fail with booleans
     .And("order total is $12.00", order => Expect.For(order.Total).ToBe(12.00m)) // Or Assertions
     .AssertPassed();

The keywords map one-to-one with the business story. Each step is explicit and composable, and the whole chain is easy to read—even for someone outside the dev team. Because the language matches what stakeholders already use, the test itself becomes a living contract.

Unit tests that read like behavior

Behavior-driven style isn't just for top-level acceptance tests. It works equally well for small pieces of logic: a pure function, a discount rule, a transformer. By expressing them as Given/When/Then, you get readability—tiny scenarios that explain the intent before diving into implementation detail—and design pressure, because the format gently encourages pure, composable functions.

Example: a simple discount calculation.

csharp await Given("a silver customer with $100 cart", () => (Tier: "silver", Amount: 100m)) .When("discount is applied", x => Discounts.Apply(x.Tier, x.Amount)) .Then("result is $95", result => result == 95m) .AssertPassed();

Even at this scale, the benefits are obvious. You isolate the decision logic, assert outcomes in plain language, and end up with code that composes neatly into bigger flows later.

End-to-end UI tests with Playwright

TinyBDD also works at the other end of the spectrum: full-stack, end-to-end tests. Here, the key is keeping steps thin and expressive while pushing implementation detail into helpers like page objects or service wrappers. That way, the scenario text stays stable even if the UI shifts underneath.

csharp await Given("a new browser and logged-in gold user", async () => { var pw = await PlaywrightFactory.LaunchAsync(); var page = await pw.NewPageAsync(); await AuthSteps.LoginAsGoldAsync(page); return page; }) .When("user adds a $12 item to cart", async page => { await CatalogSteps.AddItemAsync(page, "SKU-123", 12.00m); return page; }) .And("proceeds to checkout with standard shipping", CheckoutSteps.StandardAsync) .Then("shipping is free", async page => { var shipping = await CartSteps.ReadShippingAsync(page); return shipping == 0.00m; }) .And("order total is $12.00", async page => { var total = await CartSteps.ReadTotalAsync(page); return total == 12.00m; }) .AssertPassed();

Scenarios like this are readable enough for a stakeholder to skim, while still giving engineers the control they need under the hood. Stable wording, deterministic helpers, and tagging (smoke, ui, checkout) all contribute to making suites like this maintainable in real CI pipelines.

Patterns that keep this maintainable

The trick to making end-to-end scenarios sustainable is resisting the temptation to let your steps do all the heavy lifting. The step chain should stay thin and intention-revealing, while the real mechanics live in helpers: page objects, domain services, or test utilities. This keeps the scenario text stable even as the implementation evolves. A good rule of thumb is that a non-technical stakeholder should be able to scan the steps and nod along without ever seeing the helper code. Deterministic helpers—free from hidden global state—are key to repeatable results. And once you have a handful of scenarios, you'll want to tag them (smoke, ui, checkout, etc.) so that CI pipelines can run fast slices for quick feedback and broader sweeps when confidence matters most.

Let tests guide your design

When you write tests in a behavior-first style, architectural friction surfaces quickly. A step that requires half a dozen parameters is rarely a coincidence—it usually means your modules are too tightly coupled. Repeating the same tedious setup across multiple scenarios suggests the absence of a proper abstraction. And if you struggle to phrase a step cleanly, the problem may not be the test at all, but the clarity of your domain language.

These moments of friction are signals. Often, the fix is to extract a pure function from a messy edge, create a port or adapter to decouple infrastructure from business rules, or split a workflow into smaller seams that deserve their own scenarios. In other words: the pressure you feel in writing the test is your design telling you what it wants to become.

BDD and the drift toward SOLID and functional design

Consistently writing scenarios has a shaping effect on code. Steps that do one clear thing align with the Single Responsibility Principle. The ability to add new scenarios without editing existing ones echoes the Open/Closed Principle. And abstractions that are narrow, well-defined, and swappable make substituting fakes and stubs trivial, pushing you toward Liskov, ISP, and DIP almost by default.

The same is true for functional composition. Pure functions naturally slide into Given/When/Then flows. Side effects are easiest to reason about when pushed to the edges—fetching in a Given, transforming in a When, and observing in a Then. And when steps are small and named, they read like a pipeline instead of a mess of conditionals. By following the test style, you often find yourself following the design style too.

A practical way to start tomorrow

If this feels overwhelming, don't boil the ocean. Start with one slice of functionality that everyone values and recognizes—maybe a login path or a simple checkout. Write just two or three scenarios, and make sure the wording mirrors how the business describes the flow. Delegate the mechanics to helpers, not the scenario text. Keep your domain logic in pure functions wherever possible so it's trivial to call from a When step. And once you've got a couple of green runs, wire in some tags so you can choose between smoke tests, integration runs, or the full suite depending on your CI needs.

As you go, pay attention to the words. If step text feels clumsy, it probably means your ubiquitous language is clumsy too. Refining that wording in collaboration with stakeholders isn't overhead—it's the work. And when naming friction crops up, it's often a smell that your design needs another seam or abstraction.

Fluent examples you can copy-paste

Unit-level:

csharp await Given("subtotal is $120 and tier is gold", () => (Subtotal: 120m, Tier: "gold")) .When("finalize price", x => Pricing.Finalize(x.Tier, x.Subtotal)) .Then("applies 10% discount", price => price == 108m) .AssertPassed();

API-level:

csharp await Given("a seeded test tenant", TestData.SeedTenantAsync) .When("posting to /invoices", async _ => await Api.PostAsync("/invoices", new { amount = 250 })) .Then("returns 201", r => r.StatusCode == 201) .And("body contains invoice id", r => r.Json.Value<string>("id") is { Length: > 0 }) .AssertPassed();

UI-level:

csharp await Given("a logged-in admin", BrowserSteps.LoginAsAdminAsync) .When("they create a user named Dana", page => AdminUsers.CreateAsync(page, "Dana")) .Then("Dana appears in the grid", page => AdminUsers.ExistsAsync(page, "Dana")) .AssertPassed();

Readable Gherkin-style output

One of the nicest touches in TinyBDD is how your scenarios report themselves when you run the tests. Pair your scenarios with the appropriate base class (TinyBddXunitBase, TinyBddXunitV3Base, TinyBddNUnitBase, or TinyBddMSTestBase), and the test runner will print structured Gherkin output alongside normal results.

That means the Given/When/Then flow you wrote doesn't just execute—it shows up exactly as you'd expect, step by step, with timings and pass/fail indicators. It turns your test logs into living specifications.

For example, here's the output from a mediator scenario:

Feature: Behavioral - Mediator (commands, notifications, streaming, behaviors)
Scenario: Send: command handler runs through behaviors and returns value
Given a mediator with pre/post/whole behaviors and a Ping->Pong handler [OK] 2 ms
When sending Ping(5) [OK] 4 ms
Then result is pong:5 [OK] 2 ms
And behaviors logged pre, whole before/after, and post [OK] 0 ms

Instead of squinting at assertions in code, you see a natural-language story of what happened. That's invaluable when sharing results with stakeholders or debugging failures in CI. And because the feature and scenario titles come from your test class and attributes, the logs stay consistent with the language you use in code reviews, planning, and conversations.

Avoiding common anti-patterns

Every test framework accumulates bad habits if left unchecked, and TinyBDD is no exception. The most obvious trap is clever wording: steps like "When magic happens" don't help anyone and fail to serve as documentation. Instead, the wording should describe an intention that a stakeholder would immediately recognize, such as "When the admin disables the account". Another trap is letting a single step conceal multiple actions or checks. Keep your flow honest: When should drive effects, and Then or And should assert results.

Setup is another danger zone. If your Given steps are littered with manual wiring of objects, it's time for factories or builders to take over. And at the UI layer, brittle selectors quickly make tests flaky; encapsulating them in page objects and using explicit test IDs pays off many times over. Avoiding these pitfalls keeps your suite readable, stable, and genuinely valuable.

The payoff

When scenarios read like the business and execute like the code, something special happens. Your tests stop being just a safety net and start becoming living documentation. They never go stale because they're executable. They provide immediate feedback on drift, so change becomes safer. They subtly nudge your codebase toward SOLID principles and functional seams. And for new developers, they become the best possible onboarding guide: open the suite, read the stories, and understand how the system behaves.

You don't need to retool your world to reach this point. Start with one scenario. Make it pass. Share it with your team. Repeat. In a few sprints, you'll have a suite of stories that stack from units to workflows, and a codebase that's easier to evolve because the behaviors are crystal clear.

Appendix — A quick PR lens

As you review changes, ask yourself: does this PR add or update scenarios that the business would recognize? Do the steps read like natural English, each mapping to a single intent? Are the domain rules isolated in pure functions rather than tangled in infrastructure? Did we create or clarify a port instead of hard-coding dependencies? Can we tag and run this slice of scenarios independently in CI?

If you can answer "yes" to most of those, you're not just writing tests—you're building shared understanding, guiding design, and accelerating delivery. That's the real promise of TinyBDD.

👉 Get TinyBDD on GitHub · NuGet · Docs

JD.Efcpt.Build: Build‑Time EF Core Scaffolding to Keep Database‑First Models in Sync

Jerrett Davis — Mon, 22 Dec 2025 05:43:45 +0000

"Where Did Database First Go?"

If you were using Entity Framework when EF Core first dropped, you probably remember the moment you went looking for database-first support and found... nothing.

EF Core launched as a code-first framework. The Reverse Engineer tooling that EF6 developers relied on (the right-click, point at a database, generate your models workflow) wasn't there. Microsoft's position was essentially "migrations are the future, figure it out." And if your team had an existing database, or a DBA who actually owned the schema, or compliance requirements that meant the database was the source of truth... well, good luck with that.

The community's response was immediate and loud. "Where did database first go?" became a recurring theme in GitHub issues, Stack Overflow questions, and the quiet frustration of developers who just wanted to talk to their database without hand-writing a hundred entity classes.

Eventually, tooling caught up. EF Core Power Tools emerged as the community answer: a Visual Studio extension that brought back the reverse engineering workflow. You could point it at a database or a DACPAC, configure some options, and generate your models. Problem solved, mostly.

But here's the thing about manual processes: they work fine right up until they don't.

The Problem That Keeps Happening

I've spent enough time in codebases with legacy data layers to recognize a pattern. It goes something like this:

A project starts with good intentions. Someone sets up EF Core Power Tools, generates the initial models, commits everything, and documents the process. "When the schema changes, regenerate the models using this tool with these settings." Clear enough.

Then time passes.

The developer who set it up leaves. The documentation gets stale. Someone regenerates with slightly different settings and commits the result. Someone else forgets to regenerate entirely after a schema change. The models drift. The configuration drifts. Nobody's quite sure what the "correct" regeneration process is anymore, so people just... stop doing it consistently.

This isn't a dramatic failure. It's a slow erosion. The kind of problem that doesn't announce itself until you're debugging a production issue and realize the entity class doesn't have a column that's been in the database for six months.

If you've worked in a codebase long enough, you've probably seen some version of this. Maybe you've been the person who discovered the drift. Maybe you've been the person who caused it. (No judgment. We've all been there.)

The frustrating part is that the fix is always the same: regenerate the models, commit the changes, remind everyone to regenerate after schema changes. And then six months later, you're having the same conversation again.

Why Manual Regeneration Fails

Let's be specific about what goes wrong, because understanding the failure modes is the first step toward fixing them.

The ownership problem. Whose job is it to regenerate after a schema change? The person who changed the schema? The person who owns the data layer? The tech lead? Nobody has a clear answer, which means sometimes everyone does it (chaos) and sometimes nobody does it (drift).

The configuration problem. EF Core Power Tools stores settings in JSON files. Namespaces, nullable reference types, navigation property generation, renaming rules. There are dozens of options. If developers regenerate with different configurations, you get inconsistent output. Same database, different generated code.

The tooling problem. Regeneration requires Visual Studio with the extension installed. CI servers don't have Visual Studio. New developers might not have the extension. Remote development setups might not support it. The process that works on one machine doesn't necessarily work on another.

The noise problem. Regeneration often produces massive diffs. Property reordering, whitespace changes, attribute additions. Stuff that doesn't represent actual schema changes but clutters up the commit. Developers learn to distrust regeneration diffs, which makes them reluctant to regenerate, which makes the problem worse.

The timing problem. Even when everyone knows the process, there's no enforcement. You can commit code that references a column the models don't have, and the build might still pass if nothing actually uses that code path yet. The error surfaces later, in a different context, when the connection to the original schema change is long forgotten.

None of these are individually catastrophic. Together, they add up to a process that works in theory but fails in practice.

The Idea

Here's the thought that eventually became this project: if model generation can be invoked from the command line (and it can, via EF Core Power Tools CLI), then model generation can be part of the build.

Not a separate step you remember to run. Not a manual process with unclear ownership. Just part of what happens when you run dotnet build.

The build already knows how to compile your code. It already knows how to restore packages, run analyzers, produce artifacts. Adding "generate EF Core models from the schema" to that list isn't conceptually different from any other build-time code generation.

If the build handles it, the ownership question disappears. The build owns it. If the build handles it with consistent configuration, the drift disappears. Everyone gets the same output. If the build handles it on every machine, the tooling problem disappears. No special extensions required.

This is JD.Efcpt.Build: an MSBuild integration that makes EF Core model generation automatic.

How It Actually Works

The package hooks into your build through MSBuild targets that run before compilation. When you build, it:

Finds your schema source. Either a SQL Server Database Project (.sqlproj) that gets compiled to a DACPAC, or a connection string pointing to a live database.
Computes a fingerprint. A hash of all the inputs: the DACPAC or schema metadata, the configuration file, the renaming rules, any custom templates. This fingerprint represents "the current state of everything that affects generation."
Compares to the previous fingerprint. If they match, nothing changed, and generation is skipped. If they differ, something changed, and generation runs.
Generates models. Using EF Core Power Tools CLI, same as you'd run manually, but automated. Output goes to obj/efcpt/Generated/ with a .g.cs extension.
Adds generated files to compilation. Automatically. You don't edit your project file or manage includes.

The fingerprinting is what makes this practical. You don't want generation running on every build. That would be slow and developers would hate it. The fingerprint check is fast (XxHash64, designed for exactly this kind of content comparison), so incremental builds have essentially zero overhead. Generation only runs when inputs actually change.

Two Ways to Get Your Schema

Different teams manage database schemas differently, so the package supports two modes.

DACPAC Mode is for teams with SQL Server Database Projects. You have a .sqlproj that defines your schema in version-controlled SQL files. The package builds this project to produce a DACPAC, then generates models from that DACPAC.

<PropertyGroup>
  <EfcptSqlProj>..\Database\MyDatabase.sqlproj</EfcptSqlProj>
</PropertyGroup>

This is nice because your schema is code. It lives in source control. Changes go through pull requests. The DACPAC is a build artifact, and models are derived from that artifact deterministically.

Connection String Mode is for teams without database projects. Maybe you apply migrations to a dev database and want to scaffold from that. Maybe you're working against a cloud database. Maybe you just don't want to deal with DACPACs.

<PropertyGroup>
  <EfcptConnectionString>$(DB_CONNECTION_STRING)</EfcptConnectionString>
</PropertyGroup>

The package connects, queries system tables to understand the schema, and generates from that. The fingerprint is computed from the schema metadata, so incremental builds still work. If the schema hasn't changed, generation is skipped.

Both modes use the same configuration files and produce the same kind of output. They just differ in where the schema comes from.

Setting It Up

The minimum setup is almost trivial:

<ItemGroup>
  <PackageReference Include="JD.Efcpt.Build" Version="1.0.0" />
</ItemGroup>

If you have a .sqlproj in your solution and an efcpt-config.json in your project directory, that's it. Run dotnet build and models appear.

For more control, you add configuration. The efcpt-config.json controls generation behavior:

{
  "names": {
    "root-namespace": "MyApp.Data",
    "dbcontext-name": "ApplicationDbContext"
  },
  "code-generation": {
    "use-nullable-reference-types": true,
    "enable-on-configuring": false
  }
}

The enable-on-configuring: false means your DbContext won't have a hardcoded connection string. You configure that in your DI container, where it belongs.

If your database uses naming conventions that don't map cleanly to C#, you add renaming rules:

[
  {
    "SchemaName": "dbo",
    "Tables": [
      {
        "Name": "tbl_Users",
        "NewName": "User",
        "Columns": [
          { "Name": "user_id", "NewName": "Id" }
        ]
      }
    ]
  }
]

Now tbl_Users.user_id becomes User.Id. The database can keep its conventions, your C# code can have its conventions, and the mapping is explicit and version-controlled.

What About Custom Code?

A reasonable concern: "I have computed properties and validation methods on my entities. Won't regeneration overwrite those?"

This is what partial classes are for.

The generated entity is one half:

// obj/efcpt/Generated/User.g.cs
public partial class User
{
    public int Id { get; set; }
    public string Email { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

Your custom logic is the other half:

// Models/User.cs
public partial class User
{
    public string FullName => $"{FirstName} {LastName}";

    public bool HasValidEmail => Email?.Contains("@") ?? false;
}

Both compile into a single class. The generated half gets regenerated every build. Your custom half stays exactly as you wrote it.

This separation is actually cleaner than mixing generated and custom code in the same file. You know at a glance what's generated (.g.cs in obj/) and what's yours (everything else).

CI/CD Without Special Steps

One of the pain points I mentioned earlier was CI/CD. Manual regeneration doesn't work in automated pipelines. You're stuck either committing generated code (merge conflicts) or maintaining custom regeneration scripts (fragile).

With the build handling generation, CI just works:

steps:
  - uses: actions/checkout@v4

  - name: Setup .NET
    uses: actions/setup-dotnet@v4
    with:
      dotnet-version: '10.0.x'

  - name: Build
    run: dotnet build --configuration Release
    env:
      DB_CONNECTION_STRING: ${{ secrets.DB_CONNECTION_STRING }}

No special steps for EF Core generation. The build handles it. On .NET 10+, the package uses dotnet dnx to execute the tool directly from the package feed without requiring installation. On older versions, it uses tool manifests or global tools.

Pull requests that include schema changes automatically include the corresponding model changes, because both happen during the build. Schema and code are validated together.

When Things Go Wrong

Things will go wrong. Here's how you figure out what happened.

Enable verbose logging:

<PropertyGroup>
  <EfcptLogVerbosity>detailed</EfcptLogVerbosity>
</PropertyGroup>

Build output now includes exactly what's happening: which inputs were found, what fingerprint was computed, whether generation ran or was skipped.

Check the resolved inputs:

After a build, look at obj/efcpt/resolved-inputs.json. This shows exactly what the package found for each input. If something's wrong, you'll see it here.

Inspect the fingerprint:

The fingerprint is stored at obj/efcpt/fingerprint.txt. If generation is running unexpectedly (or not running when it should), the fingerprint tells you whether inputs changed from the package's perspective.

Who This Is For

I want to be honest about fit.

This is probably for you if:

You're doing database-first development and you've experienced the regeneration coordination problem. The "did someone regenerate?" question has come up, and the answer wasn't always clear.

Your schema changes regularly. If you're shipping schema changes weekly, manual regeneration becomes friction.

You want builds that work identically everywhere. Local machines, CI servers, new developer laptops. Everyone should get the same generated code from the same inputs.

This probably isn't for you if:

Your schema is essentially static. If schema changes are rare, manual regeneration isn't that painful.

You're using code-first migrations. If migrations are your source of truth, you're solving a different problem.

You're not using EF Core Power Tools already. This package automates EF Core Power Tools; if you're using a different generation approach, this doesn't apply.

The Groan, Addressed

"Where did database first go?"

It's been years since EF Core launched without reverse engineering, and the tooling has caught up. EF Core Power Tools exists. The CLI exists. The capability is there.

But capability isn't the same as workflow. Having the tools isn't the same as having a process that works reliably across a team, across time, across environments.

JD.Efcpt.Build is an attempt to close that gap. To take the capability that exists and make it automatic. To make the build the owner of model generation, so humans don't have to remember to do it.

Your database schema is the source of truth. This package just makes sure your code reflects that truth, every time you build, without manual intervention.

One less thing to coordinate. One less thing to forget. One less thing to go wrong in production because a manual step got skipped.

That's the pitch. Give it a try if it fits your situation.

JD.Efcpt.Build is open source and available on NuGet.

You Don't Hate Abstractions

Jerrett Davis — Mon, 08 Dec 2025 01:08:42 +0000

It’s an hour until you’re free for the weekend, and you’re trying to knock out one
last ticket before you escape into whatever assuredly action-packed plans await you.
You spot a seemingly harmless task: "Add Middle Initial to User Name Display."

You chuckle. Easy. A palate cleanser. A victory lap.

You assign the ticket, flip it from New to Active, and let your IDE warm up

while you drift into a pleasant daydream about not being here.

But then the search results begin to appear.

Slowly. Line by line.

And your reverie begins to rot.

IUserNameStrategy, UserNameContext, UserNameDisplayStrategyFactory,

StandardUserNameDisplayStrategy, FormalUserNameDisplayStrategy,

InformalUserNameDisplayStrategy, UserNameDisplayModule, …

Incredulous, your chuckle hardens into a throat-scraping noise somewhere
between a laugh and a cry.

"What in the Gang-of-Fuck is happening here," you think, feeling your pulse tick up.
"Either someone read Refactoring.Guru like it was scripture and decided to
baptize the codebase in every pattern they learned, or a grizzled enterprise
veteran escaped some Netflix-adjacent monolith and is trying to upskill in
TypeScript. Because surely no sane developer would build this much redirection
for such a trivial feature… right?"

That tiny, spiraling task is a perfect microcosm of a continuous debate across engineering circles: when does abstraction help, and when does it become a hindrance?

I recently stumbled across the humorous article You're Not Building Netflix: Stop Coding Like You Are by Adam — The Developer. But though it resonates in many ways, its broader critique is ultimately misdirected.

Adam opens with a more complete version of the code mocked in my prologue, and uses the verbosity and obscurity of that abstraction pile as the springboard for a rebuke of using enterprise patterns pretty much across the board. While the author does allow for some abstractions, they're limited in application and scope.

The problem isn’t that the complaint is wrong. It’s that it points the finger at the wrong culprit, just about literally missing the forest for the trees.

Abstractions are fundamental and essential. They are the elementary particles of software, the quarks and leptons that bind into the subatomic structures that become the atoms our earliest techno-wizards fused into molecules. Today we combine those same basic elements into the compounds and contraptions made for use by millions. Without abstractions, we are left helpless in the ever-increasing parallel streams of pulsating electrical currents, rushing through specialized, intricately forged rocks that artisan wizards once trapped lightning inside and somehow convinced to think.

But even with all that power at our disposal, the way we use these building blocks matters. Chemistry offers a fitting parallel. Food chemists, for example, have spent decades learning how to repurpose industrial byproducts into stabilizers, textures, preservatives, and anything else that can be quietly slipped into a recipe. Much of this work is impressive and innovative, but some of it is little more than creative waste disposal disguised as convenience: a brilliant hack in the short term and a lingering problem in the long one.

Developers can fall into the same pattern. We learn a new technique or pattern or clever trick and then spend the next year pouring it into every beaker we can find. We are not always discovering better processes. Sometimes we are just repackaging the same product and calling it progress. When that happens, we are not solving problems. We are manufacturing new ones that future maintainers will curse our names over.

A developer must be architect, engineer, mechanic, and driver all at once. It is fine to know how to fix a specific issue, but once that problem is solved, that knowledge should become a building block for solving the next one. If we keep returning to maintain the same solution day after day, then what we built was never a solution at all. It was a slow-burning maintenance burden that we misfiled as "done."

Abstractions exist to reduce complexity, not to multiply it. Their purpose is to lighten the cognitive load, to lift the details off your desk so you can see the shape of the problem in front of you. Terse, repetitive, wire-on-the-floor code that looks like it tumbled out of a flickering green CRT from 1999 may impress the authors who have stared at machine code long enough to discern hair color from a data stream, but it does not serve the broader team or the system that outlives them. Abstractions only do their job when they are aligned with the actual problem being solved, and that brings us to the part many developers skip entirely: modeling your software after the problem you are solving.

Seeing the Problem Before Solving It

When you build a system, any system, even a disposable script, the first responsibility is understanding why it exists. What problem does it address. Has that problem been solved before. If so, what makes the existing solution insufficient for you now. Understanding that difference is the foundation that everything else must sit on.

I learned this the hard way as a homeowner. My house is old enough to have grounded me if I talked back to it as a teenager. A couple of years ago we went through a near-total remodel. We did some work before and shortly after our daughter was born, but within a year new problems started surfacing. We brought in a structural engineer. The slab foundation was heaving. After some exploration we discovered the culprit: the original cast iron sewage line had split along both the top and bottom, creating pressure changes and settling issues throughout the house.

The fix was not small. We pulled up every inch of flooring. Replaced baseboards. Repaired drywall. Fixed the broken line. Repainted entire sections. Redid trim. Installed piers. Pumped in foundation foam. Cashed in favors. Lost many weekends. And yet, even with all that, it still cost far less than buying an equivalent house in the current market at the current rates.

The lesson is simple. Things are rarely a total loss. Even when a structure looks hopeless, even when someone has effectively set fire to best practices, even when regulations or markets or technologies have shifted dramatically, there are almost always assets worth salvaging inside the wreckage. You should not bulldoze unless you know you have truly exhausted the alternatives.

Before throwing away any system and starting another from scratch, assess what you already have. Understand what is broken, what is sound, and what simply needs reinforcement. Software, like houses, tends to rot in specific places for specific reasons. Understanding those reasons is what separates renovation from reinvention.

The Nightstand Problem

The same principle applies at a smaller scale. You may already own a perfectly functional house with perfectly functional furniture, yet still want a nightstand you do not currently possess. Your choices are straightforward. You can hope someone has decided to let go of one that happens to meet your criteria. That is the open source gamble. You can buy one, constrained only by budget and whatever definition of quality the manufacturer is committed to that week. Or you can build one yourself, limited only by your skills, imagination, and tolerance for sawdust.

If your goal is personal satisfaction or experimentation, then by all means build the nightstand. But if your goal is to sell or support a product that helps make money, you are no longer just hobby-carpenting. You are operating in the domain of enterprise software.

And when you are building enterprise software, you must view the system from the top down while designing from the bottom up. From the top down, you think about every consumer of your system. In academic terms these are actors. Any system intended to be used, whether by humans or machines, is defined by the interactions between its actors and its responsibilities. Even an autonomous system is both an actor and the architected environment it operates within.

This perspective matters because it forces your abstractions to model the real world rather than some internal taxonomy of clever names. Good abstractions emerge from an understanding of the domain. Bad abstractions emerge from an understanding of a design pattern book.

And if you want maintainability, clarity, and longevity, you always want the first.

Building from Both Directions

Designing software means working from two directions at once. On one hand, you must understand the behavior your system must exhibit. On the other hand, you must understand the shape of the world it lives in. Systems are not invented whole cloth; they crystallize out of the interactions between intentions and constraints. If you ignore either direction, you end up with something brittle, confused, overbuilt, or perpetually unfinished.

There is nothing sacred about any particular architectural style. Pick Domain-Driven, Clean, Vertical Slice, Hexagonal, Layered, or something entirely different. The choice matters far less than your consistency and your commitment to encapsulating concerns properly. Different problems require different arrangements of the same conceptual ingredients. From high altitude, two domains may look identical. Once you descend toward the details, you often discover that one is a bird and the other is an airplane. The trick is knowing when to zoom out and when to zoom in.

Plenty of developers jump immediately into code, but the outside of the system is always the real beginning. What is it supposed to do. Who uses it. Who does it talk to. Who builds it. Who runs it. Who deploys it. Who monitors it. How do you prove it works. These questions define the problem space, and the problem space determines the boundaries and responsibilities your abstractions must reflect.

Even something as small as a script must obey this reality.

Consider a simple provisioning script. First it reads a certificate from the local filesystem so it can authenticate with a remote host. Next it opens an SFTP connection to a distribution server and retrieves a zip file. Then it extracts the archive to a temporary directory provided by the operating system. Finally it executes whatever installers or configuration commands the archive contains.

On the surface this is straightforward, yet every step is shaped by the environment in which it operates. Tools differ between platforms. Available executables change. File paths and separators vary. Temporary directory locations vary. Even the existence or reliability of SFTP clients varies. None of this means we must implement every possible alternative upfront, but it does mean we should acknowledge the existence of alternatives and avoid designing ourselves into a corner where adding support later requires rewriting the entire script.

This principle scales upward. You may choose to place your application data inside a database, but scattering SQL statements across your codebase is an anti-pattern in nearly any architecture not explicitly about database engines or ORM internals. Unless you are writing an RDBMS, data access is rarely the star of the show. The real substance lives in the application logic that interprets, transforms, regulates, or composes that data. Mixing data access concerns directly into that logic creates friction. Separating them reduces friction, which improves maintainability, which improves confidence, which improves speed.

The guiding question is always the same: does this choice help my system model the problem more clearly, or does it merely model my current implementation?
If it is the former, great. If it is the latter, you are accumulating technical debt even if the code looks clean.

Abstractions aligned with the domain allow your system to grow gracefully. But abstractions aligned with your tooling force your system to grow awkwardly and inconsistently.

This is the difference between designing from both directions and designing from just one.

Behavior as the Backbone of Architecture

At some point in every software project, the discussion inevitably turns to architecture. Engineers debate whether they should adopt Domain-Driven Design or Clean Architecture, whether their services ought to be hexagonal, layered, vertical-sliced, modular, or some other fashionable geometric configuration, and whether interfaces belong everywhere or nowhere at all. These conversations are interesting, even entertaining, but they often drift into abstraction for abstraction’s sake. The problem is rarely the patterns themselves; rather, it is that these debates frequently occur in a vacuum, disconnected from the actual behaviors the system must exhibit. Humans love patterns, but software only cares about whether it does the right thing.

The most reliable way to design a system, therefore, is to begin with its behavior. A system exists to do something, and if we do not articulate that something clearly, everything downstream becomes guesswork and improvisation. This is precisely where behavior-driven development demonstrates its value. I explore this more deeply in BDD: Make the Business Write Your Tests, but in short, BDD forces us to express the responsibilities of the system in language that is precise, verifiable, and shared by both technical and nontechnical stakeholders. A behavior becomes a specification, a test, a boundary, and a contract all at once.

From an architectural perspective, this shift in thinking is transformative. When we model the largest and most meaningful behaviors first and place an abstraction around them, we create an outer shell that defines the system at a conceptual level. From there, we move inward, breaking behaviors down iteratively into smaller and more specific responsibilities. Each division suggests a natural abstraction, but these abstractions are not arbitrary. They emerge directly from the behavior they represent. They are shaped not by the developer’s preferred patterns but by the needs of the domain itself. This recursive approach ensures that abstractions mirror intent rather than implementation details.

Importantly, this recursion is not fractal. We are not attempting to subdivide reality endlessly. Rather, we refine behaviors only until they are sufficiently well understood to be implemented cleanly. Much as one does not explain quantum chromodynamics to teach someone how to scramble an egg, we do not decompose software beyond what clarity and accuracy require. And while many languages encourage the use of interfaces as the primary mechanism for abstraction, the interface is not the abstraction itself. It is merely a convenient way to enforce a contract. The real abstraction is the conceptual boundary it represents. Whether that boundary is expressed as an interface, a type, a configuration object, or a module is irrelevant as long as the contract is clear and consistent.

This is why starting with abstractions like an IHost that orchestrates an IApplication works so well. These constructs mirror the system’s highest-level behaviors. Once defined, they allow us to drill inward, step by step, carving out responsibilities until the domain takes shape as a set of interlocking, behavior-aligned components. When abstractions are created this way, they tend to be stable. They align with the problem domain rather than the transient needs of a particular implementation, and therefore they seldom need to change unless the underlying behavior changes.

Frequent modification of an abstraction is a warning sign. A well-formed abstraction typically changes only under three conditions: the business behavior has evolved, an overlooked edge case has surfaced, or the original abstraction contained a conceptual flaw. Outside of those circumstances, the need to repeatedly modify an abstraction usually indicates that its boundaries were drawn incorrectly. When adjusting one behavior forces changes across multiple components, the issue is rarely "too many" or "too few" abstractions in an abstract sense. Instead, it is a failure of alignment. The abstraction does not adequately contain the concerns it is supposed to model, and complexity is leaking out of its container and into the rest of the codebase.

Modern tooling makes this problem even more evident. With the availability of source generators, analyzers, expressive type systems, code scaffolding, and dynamic configuration pipelines, there is increasingly little justification for sprawling boilerplate or repetitive structural code. Boilerplate is not a mark of engineering rigor. It is simply untested and uninteresting glue repeated dozens of times because someone did not take steps to automate it. Good abstractions, by contrast, elevate meaning. They allow the domain to be expressed directly without forcing the developer to wade through noise.

This leads naturally to what I consider the ideal state of modern development: a system that is entirely automated from the moment code touches a repository until the moment it reaches a production-like environment. Compilation, testing, packaging, deployment, orchestration, and infrastructure provisioning should not require human involvement. The only manual step should be expressing intent in the form of new or updated behaviors. Every function that exists within the system should originate as a behavior-driven specification capable of running the entire application inside a controlled test environment, complete with containerized dependencies and UI automation tools such as Playwright. Those same tests should also be able to stub dependencies so the scenarios can run in isolation. When the system itself is treated as the first unit under test, orchestration becomes a priority rather than an afterthought.

Achieving this level of automation depends on stability, and that stability depends on disciplined abstraction. Any element that may vary across environments, including configuration values, credentials, infrastructure, connection details, and policies, must be isolated behind settings and contracts that the application can consume without knowing anything about the environment it runs in. Once this encapsulation is in place, behavior-driven specifications can operate confidently, verifying the correctness of the system from the outside in even while its internal components remain free to evolve.

Finally, it is worth stating explicitly that hand-writing repetitive boilerplate code in a CRUD-heavy application, such as repositories, controllers, mappers, DTOs, validators, or entire edge-to-edge layers, is not admirable craftsmanship. It is busywork. If you have twenty entities with identical structural behavior and you are manually writing twenty sets of nearly identical files, the issue is not insufficient discipline. It is insufficient automation. Whether through source generators, templates, reflection-based pipelines, or dynamic modules, these problems can and should be solved generically. Engineers should focus their manual effort on the places where meaning lives: the domain, the behavior, and the boundaries.

Good abstractions do not eliminate complexity; they contain it. Bad abstractions distribute it. And behavior-driven, problem-first design is how we tell the difference.

From Story to Spec: Describing Behavior First

To make this concrete, return to our original "Add Middle Initial to User Name Display" ticket. Most teams would handle this with a couple of unit tests directly against whatever UserNameService or UserNameFormatter happens to exist. The tests would exercise a particular class, call a particular method, and assert on a particular string. That can work, but it starts at the implementation, not at the behavior.

If instead we begin with behavior, the specification sounds more like this:

When a user has a middle name, show the middle initial between the first and last name.
When a user does not have a middle name, omit the gap entirely.
When a display style changes (for example, "formal" versus "informal"), the rules about how the middle initial appears should still hold.

That is the contract. It does not mention classes, factories, or strategies. It talks about what the system must do from the outside.

With something like my project TinyBDD, that kind of behavior becomes executable in a fairly direct way. Using the xUnit adapter, a scenario might look like this:

using TinyBDD.Xunit;
using Xunit;

[Feature("User name display")]
public class UserNameDisplayScenarios : TinyBddXunitBase
{
    [Scenario("Standard display includes middle initial when present")]
    [Fact]
    public async Task MiddleInitialIsRenderedWhenPresent()
    {
        await Given("a user with first, middle, and last name", () =>
                new UserName("Ada", "M", "Lovelace"))
            .When("formatting the user name for standard display", user =>
                UserNameDisplay.Standard.Format(user))
            .Then("the result places the middle initial between first and last", formatted =>
                formatted == "Ada M. Lovelace")
            .AssertPassed();
    }

    [Scenario("Standard display omits missing middle initial")]
    [Fact]
    public async Task NoMiddleInitialWhenMissing()
    {
        await Given("a user with only first and last name", () =>
                new UserName("Ada", null, "Lovelace"))
            .When("formatting the user name for standard display", user =>
                UserNameDisplay.Standard.Format(user))
            .Then("no dangling spaces or periods appear", formatted =>
                formatted == "Ada Lovelace")
            .AssertPassed();
    }
}

In these scenarios, the behavior is the first-class citizen. The test does not care whether you use a UserNameDisplayStrategyFactory, a dependency-injected IUserNameFormatter, or a static helper hidden in a dusty corner of your codebase. It cares that given a user, when you format their name, you get the right string.

The abstractions are already visible in the code, but only as a side effect of expressing behavior:

UserName represents the domain concept of a person’s name, not a UI or persistence model.
UserNameDisplay.Standard represents a particular display style that the business cares about.
The behavior is encoded in the transition from UserName to the formatted string, not in a particular class hierarchy.

Notice what is not present: we do not have separate strategies for every permutation of name structure, locale, and display preference. We have a single coherent abstraction around "displaying a user name in the standard way," and the test drives the rules we actually need.

Letting Abstractions Fall Out of the Domain

Once you have a behavior-focused spec, the abstractions almost draw themselves. One reasonable implementation might look like this:

public sealed record UserName(
    string First,
    string? Middle,
    string Last);

public interface IUserNameDisplay
{
    string Format(UserName name);
}

public sealed class StandardUserNameDisplay : IUserNameDisplay
{
    public string Format(UserName name)
    {
        if (!string.IsNullOrWhiteSpace(name.Middle))
        {
            return $"{name.First} {name.Middle[0]}. {name.Last}";
        }

        return $"{name.First} {name.Last}";
    }
}

public static class UserNameDisplay
{
    public static readonly IUserNameDisplay Standard = new StandardUserNameDisplay();
}

This is not an argument that every trivial formatting problem deserves an interface and a concrete class. You could inline this logic in a static helper and your tests above would still pass. The point is that the abstraction here is small, meaningful, and directly aligned with the behavior we care about. If later the domain grows to include multiple display styles, cultures, or localization concerns, there is already a clear seam to extend. You can introduce additional IUserNameDisplay implementations where and when they are genuinely needed, not because a pattern catalog declared that every noun deserves a factory.

If, however, you discover that adding a new behavior requires touching half the classes in the system, that is a sign you have modeled implementation variants rather than domain concepts. The behavior spec remains constant; the code churn reveals where your abstractions are misaligned.

Scaling the Same Idea Up to the System Level

So far this is all very local. A name goes in, a formatted string comes out. Real systems have much more interesting behaviors: accepting traffic, orchestrating workflows, integrating with external services, healing from transient failures, deploying safely, and so on.

The same discipline still applies. You can treat the application itself as the unit under test and express its behavior with the same style of specification. A high-level scenario might read something like this:

Given a configured application host and its dependencies
When the host starts
Then the public API responds to a health probe
And all critical services report healthy
And any failing dependency is surfaced clearly rather than silently ignored

As an executable TinyBDD scenario, that might look like:

using TinyBDD.Xunit;
using Xunit;

[Feature("Application startup and health")]
public class ApplicationHealthScenarios : TinyBddXunitBase
{
    [Scenario("Host starts and exposes a healthy API surface")]
    [Fact]
    public async Task HostStartsAndReportsHealthy()
    {
        await Given("a test host with default configuration", () =>
                TestApplicationHost.CreateDefault())
            .When("the host is started", async host =>
            {
                await host.StartAsync();
                return host;
            })
            .Then("the health endpoint returns OK", async host =>
                await AssertHealthEndpointOk(host, "/health"))
            .And("all critical health checks pass", async host =>
                await AssertCriticalChecksPass(host))
            .AssertPassed();
    }

    private static Task AssertHealthEndpointOk(TestApplicationHost host, string path)
    {
        // This could exercise a real HTTP endpoint against a TestServer or containerized instance.
        // The assertion lives here, but the behavior is defined in the scenario above.
        throw new NotImplementedException();
    }

    private static Task AssertCriticalChecksPass(TestApplicationHost host)
    {
        // Could query IHealthCheckPublisher, metrics, logs, or an in-memory probe endpoint.
        throw new NotImplementedException();
    }
}

The implementation details behind TestApplicationHost are intentionally omitted here, because they are not the main point. What matters is that at the boundary, we are still describing behavior: the host starts, the API responds, health checks pass. Internally, TestApplicationHost can wrap an IHost, use Testcontainers, spin up a WebApplicationFactory, or compose a full stack in Docker. The abstraction exists to let the behavior remain stable while infrastructure details evolve.

This is the same pattern you used on the small scale with UserNameDisplay, only now it operates at the level of the entire application. The outermost abstraction represents the system as it is experienced from the outside. Everything underneath exists to satisfy that experience.

Declarative Core, Automated Edge

Once specifications like these exist, they become the backbone of your automation. The natural end state is a development flow where:

A new behavior is introduced as a TinyBDD scenario.
That scenario boots the application in a realistic but controlled environment.
The rest of the stack compiles, configures, and deploys itself into a test harness without manual intervention.
The same scenarios run in local, CI, and pre-production environments, with only configuration differing between them.

The actual application code can then remain highly declarative. Controllers or handlers describe what should happen when a request arrives. Domain services express rules and policies in terms of value objects and aggregates. Infrastructure concerns hide behind interfaces and adapters. Source generators or templates can remove boilerplate around repetitive CRUD or mapping concerns. The tests remain focused on behavior: does the system do what we said it would do.

Abstractions in this world are not ornamental. They are the scaffolding that holds the behavior in place while the infrastructure and implementation details shift around it. As long as the specifications stay clear and the boundaries remain aligned with the domain, you can move quickly without losing correctness. And if you ever find yourself adding yet another UserNameDisplayStrategyFactoryFactory just to keep a scenario passing, you will at least have a clear, behavior-centric lens through which to recognize that something has gone wrong.

Design Patterns, Declarative Thinking, and Solving the General Case

Before closing, there is one more point worth addressing, because it tends to resurface in every conversation about abstraction: the role of design patterns. Patterns are often misunderstood in practice. For some teams they become a dictionary of shapes to copy. For others they become a superstition, something to be avoided because they "feel enterprise." In reality, design patterns are nothing more than reusable expressions of relationships that occur frequently in software. They only become harmful when applied without context.

Used well, patterns are a form of declarative modeling. They describe how things relate, not how many classes must be introduced to satisfy a template. This distinction is one reason I created PatternKit
which contains fluent implementations of every GoF pattern. The aim is not to celebrate patterns for their own sake, but to show that they can be expressed clearly and idiomatically, without the ceremony that has accumulated around them over the past few decades. A fluent strategy or builder is readable because it conveys meaning, not because it adheres to a UML diagram. A properly shaped composite or decorator is useful because it matches the problem at hand, not because the catalog says "now is the time."

Patterns at their best are accelerants for thought. They give structure to complex behavior. They reveal seams in the domain. They help us express intent without prescribing a particular class arrangement. When applied declaratively, patterns become lightweight tools that reinforce clarity rather than obstacles that obscure it.

This is the same principle that guides good abstractions. We should always aim to solve the general case when appropriate, rather than re-solving the same narrow problem in twenty different places. Shared operations belong in helpers or extensions not because we want fewer lines of code, but because meaning belongs in one place rather than scattered across many. Wrapping behavior in a well-designed abstraction is not indulgence; it is about shaping the domain so the rest of the system can grow without friction. Once the domain is sufficiently modeled, higher-order helpers, pipelines, or policy objects can provide a unified vocabulary for orchestrating that domain. These are the moments when patterns shine: when they articulate a common structure behind several similar problems and offer a clean way to express the variation between them.

Patterns should not be forced; they should emerge. If you find yourself retrofitting the domain to suit a pattern, the pattern is wrong. If a pattern clarifies the domain, it is the right one. When in doubt, your behaviors and your domain model will tell you the truth.

Closing Thoughts

At every scale, from a one-line helper to a distributed system with dozens of services, the same principles hold. Begin with behavior. Shape abstractions around the real problems rather than your implementation preferences. Allow patterns to emerge naturally when they clarify meaning. Lean on automation and declarative structures to eliminate noise. Let stability arise from good boundaries rather than rigid frameworks. And above all, keep re-examining the domain as it evolves. Systems live for years; code is rewritten many times. The only reliable compass is the domain itself.

You do not hate abstractions. What you hate are the wrong ones: misplaced layers, premature hierarchies, needless ceremony, half-understood patterns applied because someone did not want to think. But abstractions that arise from behavior and domain, shaped carefully and used intentionally, are not burdens. They are the tools that let us build systems that last.

And if you stay anchored to this style of approach, you won’t end up navigating a small cavern system of strategies and factories and wondering how a middle initial turned into a guided tour of every pattern someone ever took a little too seriously. You won’t need to fear abstraction at all. Instead, you will wield it where it belongs.

BDD: Make the Business Write Your Tests

Jerrett Davis — Mon, 01 Sep 2025 22:48:53 +0000

What if the business wrote the tests, and developers just made them pass?

That's the promise of behavior-driven development (BDD). Instead of developers guessing at requirements, chasing
Slack threads, and interpreting vague Jira tickets, we let the people who know the why express it in a form
that's precise enough to execute.

Throughout my career, I've worked with teams of all shapes and sizes, and one pattern is universal:

nobody loves writing tests. Most developers grudgingly agree they're important, but tests are often seen
as a tax—time spent writing code that doesn't "ship features."

The result is predictable: coverage gaps, brittle suites, and requirements that live in Confluence but
never make it into code. Testing becomes a burden instead of a superpower.

BDD flips that dynamic. Instead of treating tests as a chore, it turns them into a shared language between
developers, QA, and the business. Suddenly, everyone is speaking the same language about features and
scenarios, and tests become the living documentation of what the system is supposed to do.

Before we dive into how this works, let's establish a few "Laws of Testing." These aren't divine truths,
but they're a solid starting point—guidelines that help ensure tests actually drive design instead of
just describing what already exists.

The Laws of Testing

No application code will be written until tests are defined.
Systems should be tested as they are meant to be used.
Automate tests to the maximum extent technically and financially feasible.
Every business requirement must have a corresponding test. If the requirement changes, the test must change.
Any code not covered by realistic, automated tests should be treated as magic—and magic should not be trusted.

Notice that I'm not prescribing a specific tool, framework, or level of granularity. These laws simply give you
a pragmatic foundation to make testing a first-class part of building software, not an afterthought.

Behavior-Driven Development

Now for the fun part: putting this into practice.

Behavior-Driven Development (BDD) is designed to bridge the gap between business stakeholders, users, developers,
QA, and everyone else involved in a project. There are many flavors of BDD, but at their core, they all focus on telling
cohesive, testable stories using a shared Domain-Specific Language (DSL).

There's a long-standing joke in IT—still true even in the post-ChatGPT era—that it's easier to teach a subject-matter
expert to code than it is to get them to clearly articulate what they actually want built.

Over the years, countless tools have promised to help non-technical folks bring their ideas to life, but theory and
practice rarely align. Everything works in theory. We can keep building better tools to bridge the gap between
decision-makers and developers, but no tool can prevent the inevitable: requirements change.

Business needs evolve constantly. Even in a perfectly stable market, a company's technology stack would still have to
adapt—whether to security updates, API deprecations, or new compliance requirements. That's why business and technology
teams need a living contract: a shared, human-readable specification of what's supposed to exist, expressed in language
that everyone can understand.

BDD provides exactly that. It takes the "what" from the business and turns it into executable specifications for developers,
ensuring the system stays aligned with today's needs—not just the assumptions written down last quarter.

What BDD Actually Is

Behavior-Driven Development (BDD) is essentially turning your acceptance criteria into executable code.

If your company already writes:

Acceptance Criteria in Jira or Azure DevOps
Business Requirement Documents (BRDs) in Word or Confluence
Test Scripts for QA teams to follow manually

…you're already halfway there. BDD simply takes those artifacts, expresses them in a precise, human-readable format,
and wires them into your test suite so they can be run automatically.

Instead of existing only as text that humans must interpret, your requirements become living specifications that
are always in sync with what the system actually does. If the system drifts, the tests fail — letting you catch gaps
before production users do.

Key ideas:

Ubiquitous language: agree on domain terms and reuse them in requirements, tests, and code.
Outside-in: start from observable outcomes (what users and the business care about) and let those drive your implementation.
Executable documentation: your feature files become a source of truth that stays up to date because failing tests force the team to update them when the business changes its mind.

Why It Clicks with the Business

BDD speaks the same language the business already uses.

Instead of:

"Verify that gold members receive free shipping on orders over $10."

Buried in a PDF or Confluence page, we can write:

Scenario: Gold member gets free shipping
  Given the customer is a "gold" member
  And they have a cart totaling $12.00
  When they checkout with standard shipping
  Then the shipping cost is $0.00
  And the order total is $12.00

Stakeholders can read and confirm this just like they'd review an acceptance test — but now this doubles as a
machine-executable test that can be run in CI.

How to Start Without Overhauling Everything

You don't need to replace all your documentation overnight. Try this:

Take an existing acceptance criterion for a small feature.
Rewrite it as a Gherkin scenario.
Wire up just enough step definitions to make it run.
Let it fail (red).
Write or adjust code until it passes (green).
Refactor code and scenario until both are clear and maintainable.

That's it — you've just done outside-in development. Over time, you can replace more of your static BRDs and
test scripts with living specs that run automatically and stay current.

By framing BDD as an evolution of what teams already do, it becomes less intimidating: you're not adding "one more thing,"
you're making what you already write executable, consistent, and always up to date.

Starting from Existing Code (The Developer + QA Perspective)

Of course, not every team has pristine requirements or well-maintained acceptance criteria.

Sometimes the only source of truth is the code itself, or a set of outdated manual test scripts in a shared folder.

That's okay — you can still apply BDD principles to what you already have.

Step 1: Surface What the Code Already Does

Start by exploring the system from the outside in, and not by reading the code first.

Walk through the application like a user would: click buttons, submit forms, run API calls.
Write down what you observe in plain language, almost as if you were writing a support guide.
Identify key flows: logins, purchases, data exports, admin tasks, error handling.

You're essentially reverse-engineering the behavior that already exists. The goal isn't to perfectly model the internals, but to describe what happens when X occurs.

Step 2: Capture Behavior as Scenarios

Turn those observations into scenarios, even if they're manual at first.

Scenario: User can reset password
  Given I am on the login page
  When I click "Forgot password"
  And I submit my email address
  Then I receive a password reset link by email
  And I can set a new password

This becomes your backfill documentation and a checklist you can use to validate future changes.

Step 3: Choose a Testing Library

Once you have a handful of scenarios, pick a suitable tool that matches your tech stack.
It doesn't have to be fancy — choose something that can:

Parse Gherkin or similar DSL (Cucumber, SpecFlow/Reqnroll, Behave, TinyBDD 😉, etc.)
Run in your CI/CD pipeline
Integrate with the type of app you have (UI automation, API tests, service-level tests)

Don't over-engineer at this stage. The goal is simply to make a scenario run end-to-end.

Step 4: Build Thin Step Definitions

When you wire up steps to code, keep the step definitions thin and reusable:

Treat them like glue code — they orchestrate, not implement.
Push logic into abstractions (page objects, API clients, domain helpers).
Keep language aligned with the business terms you captured earlier.

This separation makes your steps easy to read and your automation maintainable even as your app changes.

Step 5: Automate the Most Valuable Flows First

Don't try to automate everything on day one. Pick a few high-value, low-volatility flows:

Happy-path checkouts
Core login and authentication
Critical reporting or data pipelines

Start small, get them running reliably in CI, and expand gradually. The point is not to hit 100% coverage overnight, but to start to

gain comfort and momentum in writing BDD tests end-to-end.

By working backward from the app's behavior, you create a bridge between what the code does and what the business expects
even when no documentation exists. Over time, your automated scenarios become the new source of truth, letting developers and QA refactor or ship new features with confidence.

Bringing It All Together

Whether you're starting from crisp acceptance criteria or working backwards from a codebase that only lives in developers' heads,
the goal of BDD is the same: close the gap between what the business needs and what the code does.

You don't have to overhaul your entire testing strategy in a single sprint. You just have to start:

Write one scenario.
Get it running end-to-end.
Share it with your team.
Keep going.

Over time, you'll build up a living specification that grows with the system, catching regressions early and making onboarding new developers dramatically easier.

What a Mature BDD Practice Looks Like

A well-adopted BDD process creates a feedback loop that keeps everyone aligned:

Business & product teams write or review scenarios as part of refinement.
Developers implement features by making those scenarios pass.
QA contributes new scenarios for edge cases and validates existing ones stay green.
CI/CD pipelines run the whole suite automatically, so everyone knows the current state of the system at a glance.

When this loop is healthy, you get a shared understanding of what "done" really means, and confidence that your software still works tomorrow, next quarter, and next year.

Final Thoughts

BDD isn't a silver bullet, but it is a forcing function for clearer requirements, more reliable software, and tighter collaboration across teams.

If you've ever wished the business could "just write the tests," BDD is the closest thing we have to that dream. Start small,
stay consistent, and watch as those scenarios turn into a living, breathing specification that guides your development for years to come.

What is "Code"?

Jerrett Davis — Mon, 01 Sep 2025 22:35:00 +0000

Technology is a wonderful thing. Humans, and perhaps even our direct ancestors, have been employing it for millennia. From stone tools to quantum computers, humans can't seem to resist tinkering with whatever the universe gives them.

And with even our most remote, uncontacted relatives still in possession of weapons and shelter, it's safe to say every person on this planet experiences technology from birth to their final days. Right now, as you read this, you're surrounded by, and literally in contact with, an almost uncountable web of human inventions.

Technology shapes our lives, and in turn, we shape its future. It can be used for feats of great creation or acts of horrific destruction. Among all its branches, one of the most powerful and most accessible is code.

You don't need a factory, a lab, or a workshop to work with code. All it takes is a computer and a spark of curiosity. If you've ever stacked LEGO bricks into something from your imagination, built a spreadsheet formula to save hours of work, set a coffee maker to brew before you wake, or fixed something in a pinch with whatever was at hand, you've tapped into the same problem-solving instinct that drives programming.

At its heart, coding is the act of taking what you have and arranging it into something that does what you want. It's imagination with rules, creativity with feedback. And once you've seen something you've built come alive, whether it's a blinking LED, a tool that saves someone's day, or an app that makes a stranger smile, it's hard not to want to build more.

What is "Code"?

Code comes in many flavors. There are programming languages like C#, Assembly, C++, Rust, Python, and countless others, each with its own syntax, style, and purpose. There's G-code, the set of instructions understood by CNC mills, 3D printers, lasers, and other computer-controlled machines. Even music notation is a kind of code, a written sequence of symbols that, when interpreted, produces something meaningful.

The “code” most familiar to all of us is human language. Spoken or written, it can form relationships, transfer knowledge, and inspire change. But language is inherently ambiguous, which makes it ill-suited for telling computers exactly what to do. That's why programming languages exist: precise dialects designed for humans to read and for machines to execute without hesitation or confusion.

Put simply:

Code is a system of signals, symbols, letters, words, or other constructs used to convey a message.

At the very bottom of every modern computer lies binary — two values, usually 1 and 0, representing “on” and “off” or “true” and “false.” Working directly in binary is tedious, so we created layers of abstraction to make our lives easier.

A step above binary is assembly language. Assembly comes in many dialects, each tied to the instruction set of a specific processor. It's still “close to the metal” but far more readable than raw ones and zeros.

A (Somewhat Accurate and Still Overly Dramatic) History of Programming Languages

The history of programming languages is a tapestry of invention, frustration, and the occasional all-nighter. Imagine it told as a fantasy epic.

First came Binary, and from Binary were forged all other tongues of the machine. But the work was slow, and the scribes of silicon longed for an easier way to command their creations.

In the early 1950s, pioneers began to shape new languages: Regional Assembly Language (1951), Autocode (1952), and IPL (1954), the forerunner to LISP. Grace Hopper's FLOW-MATIC (1955) would pave the way to COBOL (1959), while FORTRAN (1957) brought the first compiler to life. The 1960s saw the birth of LISP (1958), ALGOL (1958, 1960), BASIC (1964), PL/I (1964), BCPL (1967), and B (1969), leading to the mighty C (1972).

From the 1970s onward, the floodgates opened: Pascal (1970), Smalltalk (1972), Prolog (1972), SQL (1978), C++ (1980), Ada (1983), Perl (1987), Python (1991), Java (1995), JavaScript (1995), Ruby (1995), PHP (1995), and many more.

Each era brought its own heroes, philosophies, and quirks. Some languages were swift and elegant, others sprawling and stubborn. But all of them, in their way, expanded what was possible.

Today, we live in an age of abundance. We have languages, frameworks, and tools for nearly every conceivable task. And if the exact tool you need doesn't exist, the beauty of code is that you can create it yourself.

Why Code Matters

Code is power, not in the dystopian sense, but in the sense that it lets one person shape behavior, automate work, and solve problems in ways that scale far beyond their own hands.

With code, you can:

Automate boring tasks
Create tools that help people
Control machines in the physical world
Build art, games, and interactive experiences
Invent entirely new kinds of technology

You don't need to be a professional programmer to benefit from learning it. Even small bits of code can make life easier, save time, or open the door to entirely new possibilities.

What's Next?

This post answered “What is code?” in broad strokes: its forms, history, and why it matters. In the next part of this series, we'll start laying the foundations of programming:

Variables & Data Types — the labeled containers of programming.
Operators — the tools for working with your data.
Logic & Flow — the recipes that decide what happens when.

By the time we're done, you'll not just know what code is, you'll be able to write it, read it, and use it to build something that matters to you.

Automating Nightly Local Database Refreshes from Azure Blob Storage with Docker

Jerrett Davis — Thu, 29 Feb 2024 16:54:28 +0000

Background
Prerequisites
Setting up the Docker Container
- Base Dockerfile
- Install Azure CLI
- Install SqlPackage
- Entrypoint
The Scripts
- entrypoint.sh
- initialize-database-and-jobs.sh
- download-latest.sh
- enable-authentication.sql
- reimport-database.sh
- kill-all-connections.sql
- Final Directory Structure and Dockerfile Changes
Building the Docker Container
Testing the Container
Conclusion

Background

In cloud-hosted applications, it is common to restrict access to production databases. This is a good practice, but it can
make it difficult for various teams to access the data they need for development, testing, reporting, and data analysis.
One way to solve this problem is to create a daily process that copies the production database to a location that is accessible
to the teams that need it. In this article, we will create a docker container that will download the latest backup of a
production database from Azure Blob Storage and restore it to a local SQL Server instance.

Prerequisites

This article assumes that you have already set up an automation to back up your production database to Azure Blob Storage.
If you have not done this, you can follow the instructions in this article: Automating Nightly Database Backups to Azure Blob Storage.
The script in the article is reaching end of life, and an updated version can be found here.

Docker must be installed and configured to used Linux containers on your local machine. If you do not
have Docker installed, you can download it from Docker's website.

Setting up the Docker Container

The first step is to create a Dockerfile that will be used to build the container. The Dockerfile will contain the instructions
on how to configure the container and what commands to run when the container is started. For our environment, we will
require Microsoft SQL Server to be installed in the container. We will use the official Microsoft SQL Server Docker image as a base.

Base Dockerfile

Create a new directory on your local machine and create a file called Dockerfile in the directory. Add the following content to the file:

FROM mcr.microsoft.com/mssql/server:2022-CU11-ubuntu-22.04

# Set environment variables for the container
ARG ACCOUNT_NAME
ENV ACCOUNT_NAME=$ACCOUNT_NAME
ARG ACCOUNT_KEY
ENV ACCOUNT_KEY=$ACCOUNT_KEY
ARG CONTAINER_NAME
ENV CONTAINER_NAME=$CONTAINER_NAME

ARG CRON_SCHEDULE="0 4 * * *"
ENV CRON_SCHEDULE=$CRON_SCHEDULE

ARG DATABASE_NAME=MyDatabase
ENV DATABASE_NAME=$DATABASE_NAME
ENV MSSQL_SA_PASSWORD=yourStrong(!)Password
ENV ACCEPT_EULA=Y
ENV MSSQL_PID=Developer

# Create a working directory for our tools and scripts and copy all the files from the host machine to the container
COPY . /sql
WORKDIR /sql

Install Azure CLI

To find and download the latest backup of the production database, we will need to install the Azure CLI in the container.
We'll also need wget, cron, unzip, and a few other utilities to help us automate the process. Microsoft does offer a script
to install the Azure CLI, but in my testing it did not work as expected in the Docker container. Instead, we will use
the manual installation instructions.

Update the Dockerfile to include the following lines after the WORKDIR line:

# Must be root to install packages
USER root

# Install Dependencies
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    unzip cron wget apt-transport-https \
    software-properties-common ca-certificates curl \
    apt-transport-https lsb-release gnupg && \
    rm -rf /var/lib/apt/lists/*

# Install az cli
RUN mkdir -p /etc/apt/keyrings && \
    curl -sLS https://packages.microsoft.com/keys/microsoft.asc | \
        gpg --dearmor | \
        tee /etc/apt/keyrings/microsoft.gpg > /dev/null && \
    chmod go+r /etc/apt/keyrings/microsoft.gpg && \
    AZ_DIST=$(lsb_release -cs) && \
    echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/microsoft.gpg] https://packages.microsoft.com/repos/azure-cli/ $AZ_DIST main" | \
    tee /etc/apt/sources.list.d/azure-cli.list && \
    apt-get update && \
    apt-get install azure-cli && \
    rm -rf /var/lib/apt/lists/*

Install SqlPackage

To import the backup bacpac file that we're going to download from Azure Blob Storage, we will need to install the sqlpackage utility.
This utility is used to import and export bacpac files to and from SQL Server. The utility has evergreen links
available, so we can use the link to download the latest version of the utility.

Add the following lines to the end of the Dockerfile:

# Install SQLPackage for Linux and make it executable
RUN wget -q -O sqlpackage.zip https://aka.ms/sqlpackage-linux \
    && unzip -qq sqlpackage.zip -d /sql/sqlpackage \
    && chmod +x /sql/sqlpackage/sqlpackage \
    && rm sqlpackage.zip

The above lines download the latest version of the sqlpackage utility from Microsoft's website, unzip it, make it executable, and then remove the zip file.

Entrypoint

Finally, we need to add our entrypoint script to the container. This script will be run when the container starts, and it
will perform all the necessary steps to download the latest backup from Azure Blob Storage and restore it to the local SQL Server instance.

Add the following lines to the end of the Dockerfile:

# Switch back to mssql user
USER mssql

EXPOSE 1433

CMD /bin/bash ./entrypoint.sh

We need to switch back to the mssql user to run the SQL Server process, so we make use of the USER command to do this.
The EXPOSE command tells Docker that the container listens on the specified network ports at runtime.
The CMD command specifies the command that will be run when the container starts. In this case, we are running the entrypoint.sh script.

We will make some final changes to our Dockerfile later, but for now, save the file and close it.

The Scripts

As we alluded to at the end of our Dockerfile, we need to create an entrypoint.sh script that will be run when the container starts.
Since this container is based on the official Microsoft SQL Server Docker image, we need to ensure the original entrypoint is also run
alongside our custom entrypoint script. To do this, we need to create an additional script that we will call in our entrypoint.sh script.

entrypoint.sh

Create two new files in the same directory as your Dockerfile called entrypoint.sh and initialize-database-and-jobs.sh.
Add the following content to entrypoint.sh:

#!/bin/bash
/sql/initialize-database-and-jobs.sh & /opt/mssql/bin/sqlservr

You'll note that we are running the initialize-database-and-jobs.sh script in the background and then starting the SQL Server process.
This & syntax is necessary to ensure that the original entrypoint script is also run without the docker container exiting immediately after
the script completes.

initialize-database-and-jobs.sh

Add the following content to initialize-database-and-jobs.sh:

#!/bin/bash

# wait 30 seconds for SQL Server to start up
echo "Waiting for SQL Server to start"
sleep 30s

# Download the bacpac file from the Azure Blob Storage
echo "Downloading bacpac file from Azure Blob Storage"
bash /sql/download-latest.sh $ACCOUNT_NAME $ACCOUNT_KEY $CONTAINER_NAME /sql/backup.bacpac
backupJob=$?

if [ "$backupJob" -eq 0 ]
then
    echo "Successfully downloaded bacpac file from Azure Blob Storage!"
    echo "Enabling SQL Server authentication..."
    /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P $MSSQL_SA_PASSWORD -d master -i /sql/enable-authentication.sql
    echo "SQL Server authentication enabled. Waiting for 10 seconds before importing the bacpac file..."
    sleep 10s

    # Import the bacpac file into the SQL Server
    /sql/sqlpackage/sqlpackage /a:import /sf:/sql/backup.bacpac /tsn:localhost,1433 /tdn:$DATABASE_NAME /tu:sa /tp:$MSSQL_SA_PASSWORD /ttsc:True

    # Set up 4am CRON job to re-import the database
    echo "$CRON_SCHEDULE /bin/bash /sql/reimport-database.sh" | crontab -
    echo "CRON job set up successfully"
    exit 0
else
    echo "Failed to download bacpac file from Azure Blob Storage"
    exit 1
fi

This short script does quite a few operations. First, it's recommended to wait for SQL Server to start up before attempting to connect to it.
We set up a 30-second timer to wait for SQL Server to start. We then download the latest backup from Azure Blob Storage using the download-latest.sh script.
If the download is successful, we use the built-in sqlcmd utility to enable SQL Server authentication. We then wait for 10 seconds to ensure that the
SQL Server has stabilized. We then use the sqlpackage utility to import the bacpac file into the SQL Server. Finally, we set up a CRON job to run the
reimport-database.sh script at a frequency specified by the CRON_SCHEDULE environment variable. We then exit the script with a success code.

We need to create the download-latest.sh and reimport-database.sh scripts that are called in the initialize-database-and-jobs.sh script.

download-latest.sh

Create a new file called download-latest.sh and add the following content:

#!/bin/bash

# Description: This script downloads the latest backup from an Azure Storage Account
# Usage: bash DownloadLatest.sh <storageAccountName> <storageAccountKey> <containerName> <localPath>

accountName=$1
accountKey=$2
containerName=$3
localPath=${4:-"./backup.bacpac"}

# Get the name of the latest blob
firstBlob=$(az storage blob list --account-key $accountKey --account-name $accountName -c $containerName --query "[?properties.lastModified!=null]|[?ends_with(name, '.bacpac')]|[0].name" -o tsv)

# Check if $firstBlob is not null (i.e., there are blobs found)
if [ -n "$firstBlob" ]; then
    az storage blob download --account-key $accountKey --account-name $accountName -c $containerName --name $firstBlob --file $localPath --output none
    exit 0
else
    exit 1
fi

The Azure CLI lets us write queries to filter the results of the az storage blob list command. The queries are written in
JMESPath, which is a query language for JSON. In this case, we are filtering the results to only include blobs that end with the
.bacpac extension and then selecting the first one as ordered by the lastModified property. If there are no blobs found, the script exits with a failure code.
If we find a blob, we download it to the local path specified by the localPath variable.

enable-authentication.sql

Create a new file called enable-authentication.sql and add the following content:

sp_configure 'contained database authentication', 1;
GO
RECONFIGURE;
GO

This script enables contained database authentication in the SQL Server instance. This is necessary to allow the sa user to authenticate to the database
when importing the bacpac file.

reimport-database.sh

Create a new file called reimport-database.sh and add the following content:

#!/bin/bash

echo "Downloading bacpac file from Azure Blob Storage"
bash /sql/download-latest.sh $ACCOUNT_NAME $ACCOUNT_KEY $CONTAINER_NAME /sql/backup.bacpac
backupJob=$?
if [ "$backupJob" -eq 0 ]
then
    echo "Successfully downloaded bacpac file from Azure Blob Storage!"
    echo "Kill all connections to the database"
    /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P $MSSQL_SA_PASSWORD -d master -i /sql/kill-all-connections.sql
    databaseName=$DATABASE_NAME
    existingDatabaseName="${databaseName}_$(date +%s)"
    echo "Renaming existing database to $existingDatabaseName"
    /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P $MSSQL_SA_PASSWORD -d master -Q "ALTER DATABASE $databaseName MODIFY NAME = $existingDatabaseName;"
    echo "Renamed existing database to $existingDatabaseName"
    echo "Importing bacpac file into the SQL Server"
    /sql/sqlpackage/sqlpackage /a:import /sf:/sql/backup.bacpac /tsn:localhost,1433 /tdn:$DATABASE_NAME /tu:sa /tp:$MSSQL_SA_PASSWORD /ttsc:True
else
    echo "Failed to download bacpac file from Azure Blob Storage"
    exit 1
fi

You'll notice that this script is very similar to the initialize-database-and-jobs.sh script. The main difference is that we are renaming the existing database
before importing the new bacpac file. This is necessary because the sqlpackage utility does not support overwriting an existing database.
We also need to kill all connections to the database before renaming it. We do this by running a SQL script that we will create called kill-all-connections.sql.

kill-all-connections.sql

Create a new file called kill-all-connections.sql and add the following content:

-- kill all connections to the database
DECLARE @killCommand NVARCHAR(MAX) = '';

SELECT @killCommand = @killCommand + 'KILL ' + CAST(spid AS VARCHAR) + ';'
FROM sys.sysprocesses
WHERE dbid > 4;

EXEC sp_executesql @killCommand;

As its name suggests, this script kills all connections to the database. This is necessary to ensure that we can rename the database without any active connections.

Final Directory Structure and Dockerfile Changes

If everything went to plan, your directory should look like this:

.
├── Dockerfile
├── entrypoint.sh
├── initialize-database-and-jobs.sh
├── download-latest.sh
├── enable-authentication.sql
├── reimport-database.sh
├── kill-all-connections.sql

Now before we can build the Docker container, we need to make a few final changes to our Dockerfile.
We need to copy all the files from our local machine to the container and set the correct permissions on the scripts.
Add the following lines to your Dockerfile directly after the USER root line:

RUN mkdir /home/mssql && chown mssql /home/mssql && \
    chmod +x /sql/initialize-database-and-jobs.sh && \
    chmod +x /sql/entrypoint.sh && \
    chmod +x /sql/download-latest.sh

The mkdir command creates a new directory in the container and the chown command changes the owner of the directory to the mssql user.
We then set the correct permissions on the scripts using the chmod command. Save the Dockerfile and close it.

Building the Docker Container

Now that we have all the necessary files, we can build the Docker container. Open a terminal and navigate to the directory where your Dockerfile is located.
Run the following command to build the container:

docker build -t azure-local-database-refresh .

This command will build the container using the Dockerfile in the current directory and tag the container with the name azure-local-database-refresh.
The build process may take a few minutes to complete. Once it's done, you can run the container using the following command:

docker run -e ACCOUNT_NAME=<storageAccountName> -e ACCOUNT_KEY=<storageAccountKey> -e CONTAINER_NAME=<containerName> -e DATABASE_NAME=MyDatabase -p 1433:1433 -it  azure-local-database-refresh

Replace <storageAccountName>, <storageAccountKey>, and <containerName> with the appropriate values for your Azure Blob Storage account. The -p flag maps port 1433 of the container to port 1433 of your local machine.
This allows you to connect to the SQL Server instance running in the container from your local machine. The -it flag runs the container in interactive mode, which allows you to see the output of the container in your terminal.

You should see the output of the container in your terminal. If everything is working correctly, you should see messages indicating that the bacpac file has been downloaded and imported into the SQL Server instance. The import
process can take a several minutes to complete, depending on the size of the database. Once the import process is complete, you should see a message indicating that the CRON job has been set up successfully.

Testing the Container

Now that we have our container up and running, we can test it by connecting to the SQL Server instance and verifying that the database has been restored.
Open a new terminal and run the following command to connect to the SQL Server instance running in the container:

docker exec -it <containerId> /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P yourStrong(!)Password

Replace <containerId> with the ID of your container. This command will open an interactive SQL Server prompt. Run the following command to verify that the database has been restored:

SELECT name FROM sys.databases;

If everything went to plan you should see the name of your database in the output. You can also run queries against the database to verify that the data has been restored correctly.

Conclusion

In this article, we created a Docker container that automates the process of downloading the latest backup of a production database from Azure Blob Storage and restoring it to a local SQL Server instance.
We used a combination of bash scripts and Docker to create a portable and easy-to-use solution that can be run on any machine that has Docker installed. This solution can be used to provide teams with access
to the latest production data for development, testing, reporting, data analysis, or other internal uses. The container can be run on a schedule using a CRON job to ensure that the data is always up-to-date. This solution can be
easily extended to support other databases and cloud storage providers.

The code for this solution is available on GitHub.
This docker container is also available on Docker Hub.