DEV Community: Naimul Karim

Build Smarter AI Agents: Use Deterministic Code Before Calling an LLM

Naimul Karim — Fri, 13 Nov 2026 01:41:02 +0000

There is a tempting assumption when building AI-powered applications: if an LLM can make a decision, why not ask it to make that decision every time?

It sounds reasonable. The model is already part of the application, it can interpret context, and it can handle a wide range of situations.

But there is a catch.

Not every problem needs reasoning. Some problems just need code.

If an AI agent repeatedly solves the same problem, it may be time to turn that solution into a deterministic function. Doing so can reduce inference costs, improve response times, and make the system more predictable.

This is a small architectural decision with potentially significant benefits.

The problem: asking an LLM to solve the same thing repeatedly

Imagine an AI agent that investigates failed CI/CD pipelines.

Whenever a build fails, the agent:

Reads the pipeline logs.
Interprets the error messages.
Investigates the likely cause.
Recommends what to do next.

This is a useful application of an LLM. Build logs can be long, unfamiliar, and sometimes ambiguous. The agent may need to connect several clues before identifying the root cause.

Now imagine that the same known error appears repeatedly:

error NU1301: Unable to load the service index for source.

After investigating the issue, the agent determines that the package feed is temporarily unavailable and recommends retrying package restore.

The next time the same failure occurs, should the application ask the LLM to investigate everything again?

What about the hundredth time?

Probably not. Once the pattern is understood, we can handle it with ordinary application code.

Turn a known decision into deterministic code

For example, we could introduce a small C# function that recognizes known build errors:

public string AnalyzeBuildFailure(string logs)
{
    if (logs.Contains("NU1301", StringComparison.OrdinalIgnoreCase))
    {
        return "NuGet feed may be unavailable. Check connectivity and retry package restore.";
    }

    if (logs.Contains("CS0246", StringComparison.OrdinalIgnoreCase))
    {
        return "A type or namespace could not be found. Check using directives and project references.";
    }

    if (logs.Contains("401 Unauthorized", StringComparison.OrdinalIgnoreCase))
    {
        return "Authentication failed. Check the credentials or token used by the pipeline.";
    }

    return "Unknown failure. Further investigation is required.";
}

This is a simplified example; a production implementation should account for log structure, error context, false matches, and the possibility that one error message has multiple causes.

The important idea is that known patterns can be handled without an LLM call.

Instead of sending every failure to a model, the application can first check whether it recognizes the issue. If it does, it follows a tested path. If it does not, it can escalate the problem to the LLM.

That gives us a useful division of responsibility:

Code handles known patterns and explicit rules.
The LLM handles unfamiliar situations, ambiguity, and reasoning.

What do we mean by deterministic code?

Deterministic code produces the same result for the same input, assuming the same relevant state and execution environment.

For example:

public decimal CalculateTotal(
    decimal subtotal,
    decimal taxRate)
{
    return subtotal + (subtotal * taxRate);
}

Given the same values, this function returns the same result. There is no need for an LLM to interpret the request or generate a calculation.

Compare that with asking an LLM to calculate an invoice total. The model may produce the correct answer, but it introduces unnecessary uncertainty into a task that should be handled by precise, testable business logic.

This distinction matters:

Use deterministic code when...	Use an LLM when...
The rules are known and explicit	The rules need to be inferred from context
The result must be precise and repeatable	The input is ambiguous or unstructured
The task involves calculations or validation	The task involves interpretation or summarization
The same decision is made frequently	The situation is unfamiliar or requires flexible reasoning

An LLM is not a replacement for every function in an application. It is a tool for the parts of a problem where language understanding and flexible reasoning add value.

Two principles for designing efficient AI systems

There are two practical principles worth keeping in mind.

1. If you can reliably express a decision as rules, use code

Consider a small business invoicing application.

Some features might include:

Calculating invoice totals.
Applying a predefined discount.
Validating required customer information.
Checking whether an invoice is overdue.
Updating an invoice's payment status.

These are ordinary business rules. They belong in application code, supported by unit tests.

Other features may benefit from an LLM:

Understanding a request such as, "Show me the invoices that are still outstanding from last month."
Summarizing a customer's message.
Turning an informal instruction into a structured draft invoice.
Explaining an unfamiliar error in plain language.

The goal is not to make the application less intelligent. It is to use the right tool for each responsibility.

2. If an LLM keeps solving the same problem, consider turning the solution into code

Suppose an agent repeatedly investigates API failures and discovers that a particular class of failures is caused by expired access tokens.

Initially, the LLM may be useful because it needs to examine logs and understand the situation.

But once the pattern is confirmed, checking token expiration is straightforward:

public bool IsTokenExpired(DateTime expiresAtUtc)
{
    return expiresAtUtc <= DateTime.UtcNow;
}

The application can now perform this check directly.

The same idea applies to repeated decisions in many domains:

Recognizing known CI/CD failures.
Validating API request structures.
Applying business rules.
Checking authorization conditions.
Detecting predefined data-quality issues.
Routing requests based on known categories.

A repeated LLM decision is an opportunity to ask: Can we capture what we have learned as a reliable software rule?

A hybrid architecture: deterministic code plus LLM reasoning

A practical AI agent does not need to choose between traditional code and an LLM. It can use both.

Consider a simplified workflow for our CI failure investigation agent:

                 CI Pipeline Failure
                          |
                          v
                Read and collect logs
                          |
                          v
                 Check known patterns
                          |
                +---------+---------+
                |                   |
             Recognized          Unknown
                |                   |
                v                   v
          Deterministic         Send context
             handler             to LLM
                |                   |
                v                   v
          Apply known fix       Investigate
          or recommendation    and reason
                |                   |
                +---------+---------+
                          |
                          v
                  Validate the result
                          |
                          v
                 Report the outcome

The deterministic path handles situations the system already understands. The LLM path handles cases that need further investigation.

There is an important engineering detail here: recognizing a known pattern is not the same as proving its cause.

For example, an error code may have multiple possible causes. A rule-based handler should only take an automated action when the evidence and risk level justify it. Otherwise, it should provide a safe recommendation or escalate to the LLM or a human.

This is why validation, tests, observability, and clear fallback behavior remain essential.

AI-assisted development makes this approach easier

There is another interesting part of this idea: AI coding tools can help us create the deterministic code that reduces future LLM usage.

For example, a developer can ask an AI coding assistant to:

Review recurring agent decisions or known failure cases.
Identify decisions that can be expressed as explicit rules.
Propose a small function or service to handle them.
Generate unit tests, including edge cases.
Refactor the agent to call the new function before invoking the LLM.
Help compare behavior before and after the change.

The generated implementation still needs to be reviewed and tested. An AI-generated function is not automatically correct just because it is deterministic.

But AI can reduce the effort required to turn a discovered pattern into maintainable, tested software.

This creates an interesting feedback loop:

The LLM investigates an unfamiliar problem.
Engineers verify the diagnosis.
A recurring pattern is identified.
The pattern is implemented as deterministic code.
Future occurrences use the code path.
The LLM is reserved for genuinely new or ambiguous cases.

Over time, the system can handle a larger share of familiar situations without inference.

Does this mean future AI agents will use fewer LLM calls?

Potentially, yes.

A more capable agent does not necessarily need to make more model calls. In a well-designed system, repeated reasoning can gradually become reusable software.

That does not mean every LLM interaction should be replaced with a rule. Real-world inputs change, edge cases appear, and some decisions remain inherently ambiguous. The system still needs a way to handle cases that do not match known patterns.

The objective is not to eliminate LLM calls. It is to make each call worthwhile.

A useful way to think about the architecture is:

Use deterministic code for precision, repeatability, and known business logic.
Use LLMs for interpretation, ambiguity, and unfamiliar problems.
Use tests and validation to make sure both paths behave safely.
Keep a fallback path for cases the deterministic logic cannot confidently handle.

Final thoughts

One of the biggest opportunities in AI-assisted development may not be adding AI to more parts of an application. It may be using AI to build better software around the places where AI is genuinely needed.

When an LLM solves a problem once, it provides an answer.

When we understand that solution, verify it, and turn it into tested code, we create something reusable.

That code can run repeatedly, predictably, and without another inference call.

The best AI architecture may not be the one that calls an LLM for everything. It may be the one that knows exactly when not to.

And perhaps one of the most valuable uses of AI is helping us write the code that makes future AI calls unnecessary.

Build a Simple E-commerce MVP with AI: A Step-by-Step Guide

Naimul Karim — Fri, 13 Nov 2026 01:05:13 +0000

If you've ever typed "build me an e-commerce app" into an AI tool, you know how it goes. You get something that runs, but it's not what you pictured. The login works differently than you wanted, the checkout has steps you never asked for, and half the buttons look like they came from different apps.

The problem isn't the AI. It's that you left it hundreds of decisions to guess at.

What worked for me was changing the order of things. I stopped asking for code first. Instead I ask Claude to help me write five short documents, answer its questions, and only then hand everything to Claude Code to build. The code ends up being the easy part.

This post walks through the whole process with the exact prompts I use. The stack here is Angular on the front end and ASP.NET Core on the back end, but the method works with any stack. I'll use a made-up store called QuickCart as the example. Swap in your own idea and it works the same way.

The example: QuickCart

Nothing fancy, on purpose:

Two roles: a customer and a store owner
The owner manages products. Customers browse, search, add to cart and check out
Payment is cash on delivery only, so no payment gateway to set up
Orders go Placed, Confirmed, Shipped, Delivered, and the customer can follow along

The plan

Write a PRD (what we're building, and what we're not)
Write a screen flow (every screen and journey)
Lock the tech stack to exact versions
Write a design system, and preview it as an HTML mockup
Design the database schema and API
Make an implementation plan and a CLAUDE.md
Set up your accounts and local environment (this part is on you)
Build with Claude Code
Have separate review agents check the work
Write a UAT plan and deploy

Before you start

You'll need a Claude account and Claude Code installed. On your machine, install the .NET SDK, Node.js (for the Angular CLI), and PostgreSQL (or have a hosted dev database ready). Make a project folder with a docs/ directory inside. Every document Claude writes goes there as a .md file, because Claude Code reads Markdown without any fuss.

The trick I use in every prompt

Every prompt below ends with some version of this:

Before writing anything, ask me every question you need answered.
For each question, propose a default answer so I can approve quickly.
Do not assume anything.

This is the single most useful habit I've picked up. Claude comes back with a numbered list of questions, each with a sensible default. You say "defaults for everything except number 3" and you're done in a minute. Here's what that looks like for the PRD:

Q1. Can guests check out without an account?
    Default: No. Login (email) is required to place an order.
Q2. Can customers cancel an order?
    Default: Yes, only while the status is Placed.
Q3. Is there one delivery fee or many?
    Default: One flat fee, set by the owner.
Q4. Which currency and tax handling?
    Default: Single currency, prices tax-inclusive.

Without this step, those answers still get decided. The AI just decides them quietly, and you find out later.

Step 1: The PRD

The PRD says what you're building. Just as important, it says what you're not building. I always list non-goals, because otherwise the AI helpfully adds reviews, coupons and a wishlist you never wanted.

Prompt:

I want to build "QuickCart", a simple online store web app.

Roles: Customer and Store Owner (admin).
- The owner manages products (name, description, price, image,
  category, active/inactive).
- Customers browse, search, add to cart, check out and track orders.
- Payment: Cash on Delivery only.
- Order statuses: Placed -> Confirmed -> Shipped -> Delivered,
  or Cancelled.

Out of scope: stock tracking, online payments, reviews, coupons,
refunds, multi-vendor.

Prepare a PRD/BRD. Do not include the tech stack or database.
Before writing anything, ask me every question you need answered,
with a default answer for each. Do not assume anything.

Deliverable: prd.md

The result should look something like this:

# QuickCart: Product Requirements Document
Version: 1.0 | Date: <date> | Owner: <you> | Status: Draft

## 1. Executive Summary
QuickCart is a mobile-first web store where customers order
everyday items and pay cash on delivery. One owner manages the
catalogue and fulfils orders.

## 3. Scope
### 3.1 In scope
- Product catalogue management (owner)
- Browse, search, cart, checkout (customer)
- Order lifecycle and customer-visible tracking
### 3.2 Out of scope (v1)
- Stock tracking, online payments, reviews, coupons, refunds

## 5. Functional Requirements
| ID    | Requirement                                   | Priority |
|-------|-----------------------------------------------|----------|
| FR-01 | Customer can register and log in with email   | Must     |
| FR-02 | Customer can add/remove/update cart items     | Must     |
| FR-03 | Customer can cancel an order while Placed     | Should   |
| FR-04 | Owner can mark a product inactive (hidden)    | Must     |

## 6. Acceptance Criteria
FR-03: Given an order in status Placed, when the customer taps
Cancel and confirms, then the status becomes Cancelled.

Read it properly. Changing a requirement now takes ten seconds. Changing it after the app is built takes an afternoon.

Step 2: The screen flow

The PRD tells you what the app does. The screen flow tells you what people actually see: every screen, every empty state, every "what happens if the network drops" moment.

I make Claude interview me again here, this time in four areas.

Using prd.md, create a Screen Flow document: a blueprint of every
screen and end-to-end user journey in the MVP.

Do NOT write the document yet. First interview me, grouped into:
1. Navigation architecture and transitions (primary/secondary nav,
   deep links, entry and exit points)
2. State management: empty, error and loading states
3. Page data dependencies (what populates each page, what happens
   if data is slow or missing)
4. Edge cases (session timeout, back button, cancel/exit modals)

For every question propose a default based on standard UX best
practice. The final document must be so complete that a first-time
user can navigate without support.

Deliverable: screen-flow.md

A good result gives every screen an ID and spells out its states:

## 1. Global Rules
- Customer: bottom tab bar (Home, Cart, Orders, Account)
- Owner: sidebar (Dashboard, Orders, Products, Account)
- Loading: skeletons for lists, inline spinner on buttons
- Network error: inline retry banner, cached data tagged
  "may be outdated"
- Empty state: illustration + one line + a relevant action
- Back button during checkout: Confirm Exit modal

## CUST-04: Cart
Purpose: Review items and proceed to checkout.
Entry points: Cart tab, "Added to cart" toast action.
Data shown: items, quantity steppers, line totals, order total.
States:
  - Empty: "Your cart is empty" + [Browse products]
  - Loading: skeleton rows
  - Error: retry banner, cart kept locally
Exit points: [Checkout] -> CUST-05, [Continue shopping] -> CUST-01
Notes: Inactive products show "No longer available" and block checkout.

Those IDs (CUST-04 and so on) turn out to be handy. You can say "fix CUST-04" later and nobody has to guess which screen you mean.

Step 3: The tech stack

This one gets handed to Claude Code, so there's no room for "latest" or ^1.2.0. Every dependency gets an exact version. It keeps builds reproducible, and it stops the AI from writing code for an API that changed two releases ago.

Create a tech stack document that locks every dependency to an
exact version number. It will be an input document for Claude Code.

Frontend: Angular (standalone components, TypeScript strict mode)
Backend: ASP.NET Core Web API on the current .NET LTS release
Database: PostgreSQL, accessed through Entity Framework Core
Auth: ASP.NET Core Identity with JWT bearer tokens
Hosting: Azure (App Service + Static Web Apps), with AWS as an
alternative

Rules:
- Pin the .NET SDK with global.json and Node/npm in package.json
  "engines".
- Do not recommend any library less than 1 year old with fewer
  than 10,000 GitHub stars, unless it is the official or
  first-party package for a chosen platform.
- Maximise compatibility with Claude Code.

Before finalising, ask me questions with default answers.

Deliverable: tech-stack.md

I added that age and stars rule on purpose. Popular, well-documented libraries are also the ones the AI knows best, so you get fewer weird bugs. Here's the shape of the output:

## 0. Version-check rule
Before scaffolding, verify every version: `npm view <package> version`
for npm packages, `dotnet package search <name> --exact-match` (or
nuget.org) for NuGet packages. If anything differs, STOP and report
it. Never silently substitute a version. Use exact versions in
package.json (no ^ or ~) and exact <PackageReference> versions in
.csproj files.

## 1. Runtime
| Component | Locked version | Notes                              |
|-----------|----------------|------------------------------------|
| .NET SDK  | <exact>        | LTS; pinned in global.json         |
| Node.js   | <exact>        | LTS; pinned in package.json engines|

## 2. Frontend
| Package          | Locked version | Notes                        |
|------------------|----------------|------------------------------|
| @angular/core    | <exact>        | Standalone components        |
| @angular/cli     | <exact>        | Same major as core           |
| typescript       | <exact>        | strict mode on               |
| rxjs             | <exact>        | Matches Angular peer range   |
| tailwindcss      | <exact>        | Design tokens as CSS variables |

## 3. Backend (NuGet)
| Package                                  | Locked version | Notes          |
|------------------------------------------|----------------|----------------|
| Microsoft.EntityFrameworkCore            | <exact>        | Matches .NET   |
| Npgsql.EntityFrameworkCore.PostgreSQL    | <exact>        | PostgreSQL     |
| Microsoft.AspNetCore.Identity.EntityFrameworkCore | <exact> | Users/roles   |
| Microsoft.AspNetCore.Authentication.JwtBearer | <exact>   | JWT auth       |
| FluentValidation.AspNetCore              | <exact>        | Request checks |
| xunit                                    | <exact>        | Backend tests  |

## 4. Testing
| @playwright/test | <exact> | End-to-end tests |

I left the versions as <exact> because they change all the time. Claude will fill in real ones. Check them yourself with the commands in the document before building.

Step 4: The design system

Skip this and every page ends up slightly different: a different blue here, a different corner radius there. The design system is one document that answers every "how should this look" question in advance, so Claude Code never has to improvise.

I have the PRD, Screen Flow and Tech Stack documents. Create a
Design System and Content Guidelines document for Claude Code to
build every Angular page and component from. Claude Code must not
guess how anything should look or behave.

Cover Light AND Dark mode:
- Visual identity: color palette (primary, neutral, success,
  warning, error), tone, direction for a trustworthy store UI
- Typography: heading/body fonts, sizes, weights, line heights
- Information density: comfortable / balanced / dense (recommend one)
- Layout: grid, spacing scale, breakpoints, navigation behaviour
- Border radius, borders, shadows, elevation as design tokens
- Every component with anatomy, dimensions, typography, spacing,
  colors, states (default, hover, active, focus, disabled, loading),
  accessibility and responsive behaviour: buttons, inputs, selects,
  cards, tables, badges, modals, toasts, tabs, pagination, empty,
  error and loading states, order-status timeline
- Charts: only where they genuinely help; say where a plain number
  or table is clearer
- Loading and feedback rules: when to use skeletons vs spinners
- Explicit DO and DO NOT rules
- How tokens map to the styling approach in the tech stack

Principles: clarity over decoration, familiarity over novelty,
speed over animation.

Review all previous documents and ask me questions first, with
defaults. Do not assume anything.

Deliverable: design-system.md

The detail level is the point. Something like this:

## Color tokens (CSS variables, never inline hex)
| Token               | Light     | Dark      | Usage             |
|---------------------|-----------|-----------|-------------------|
| --color-bg          | #FFFFFF   | #0A0A0A   | Page background   |
| --color-surface     | #FAFAFA   | #141414   | Cards, panels     |
| --color-border      | #E5E5E5   | #2A2A2A   | Dividers, borders |
| --color-text        | #171717   | #F5F5F5   | Body text         |
| --color-accent      | #059669   | #10B981   | Primary actions   |

## Primary Button
Height 40px | Radius 8px | Padding-x 16px | Font 14px / 500
Icon 16px | Background --color-accent | Text white
Hover: --color-accent-hover | Active: --color-accent-active
Focus: 2px ring, 2px offset | Disabled: 50% opacity, no pointer
Loading: spinner replaces icon, label stays, width unchanged

## DO NOT
- Introduce colors or spacing values that are not tokens
- Use color alone to show status (always add a label or icon)
- Create one-off component styles for a single page

See it before you build it

Once the document exists, I ask for a throwaway mockup:

Create a single-page HTML/CSS/JavaScript file that shows how my app
will look. Use the colors and iconography from design-system.md.
Show every component: all button types, dropdowns, headings, inputs,
cards, badges, tables, modals, toasts. Include a light/dark toggle.

Open it in a browser. If something looks off, fix the document now. It's far cheaper than fixing finished pages.

Step 5: The database schema and API

This is the step where mistakes hurt most, because the data model touches everything. The aim is that Claude Code follows a contract and never invents tables or endpoints on the fly.

Design the complete backend for this app (ASP.NET Core Web API +
Entity Framework Core + PostgreSQL). Cover:
- All tables, fields, relationships, foreign keys, constraints,
  indexes, and the matching EF Core entities
- Authentication (ASP.NET Core Identity + JWT) and authorization
  (roles and policies, and which endpoints each role may call)
- API endpoints: route, method, request/response shape, role
  required, and which tables each one touches
- Business rules that must be enforced on the server (for example,
  a customer may only cancel their own order while it is Placed)
- Background jobs and database-level logic, if any
- Data lifecycle: soft delete, and permanent removal after 30 days
- Audit/history requirements

Rules:
- Cross-check against the PRD, Screen Flow, Tech Stack and Design
  System. List contradictions and gaps first.
- Separate what belongs in the database from what is only a
  PRD requirement. Do not copy product concepts into tables
  without validating them.
- Evaluate storage for a startup: PostgreSQL vs file/object storage
  vs a document store. Do not add infrastructure without a clear
  reason.
- Use EF Core migrations as the source of schema changes.

Claude Code must not have to guess the schema or the API. Ask me
every question first, with defaults.

Deliverable: backend-design.md

Two of those rules do a lot of work. The cross-check catches contradictions between your earlier documents. And the "separate PRD from database" rule stops Claude from turning every sentence in the PRD into a table. For a startup, the answer to the storage question is almost always plain PostgreSQL plus file or blob storage for product images. No extra database needed.

An excerpt of the output:

## Storage decision
PostgreSQL for all relational data. Product images in blob storage
(Azure Blob Storage or S3), with only the image URL kept in the
database. No document database: no requirement needs it.

## Table: orders

create table orders (
  id               uuid primary key default gen_random_uuid(),
  customer_id      uuid not null references users(id),
  status           text not null default 'placed'
                   check (status in ('placed','confirmed','shipped',
                                     'delivered','cancelled')),
  total_amount     numeric(10,2) not null check (total_amount >= 0),
  delivery_address text not null,
  placed_at        timestamptz not null default now(),
  deleted_at       timestamptz
);
create index on orders (customer_id, placed_at desc);

## Authorization: orders
- Customer: GET /api/orders returns only rows where
  customer_id = the user id in the JWT
- Customer: POST /api/orders/{id}/cancel allowed only for own
  orders with status 'placed'
- Owner (role "Owner"): GET and PATCH on all orders
- Enforced in the API with authorization policies and an
  ownership check in the service layer. Never trust an id
  sent by the client.

## Design note: PRD vs database
The PRD says "order tracking". In the database this is a history
table (order_status_history) so the timeline can show timestamps;
a single status column cannot do that.

## Data lifecycle
Soft delete uses deleted_at plus an EF Core global query filter.
A background service (IHostedService) hard-deletes rows older than
30 days once a day.

Step 6: The implementation plan

Now you ask for a phased build plan. The most important line in this prompt is the one about what Claude Code should do when it hits something the documents don't cover. It should stop and ask you.

Using all five documents, create a sequenced, step-by-step
implementation plan that Claude Code will follow to build the app
from initialization to deployment, in phases.

Rules:
- If Claude Code reaches a decision not covered by the documents,
  it must stop and ask me. It must never guess.
- Include environment setup (.NET SDK, Node version, local
  PostgreSQL, secrets handling, local run and test commands).
- Each phase ends with a testable checkpoint.
- Backend and frontend work for the same feature belong in the
  same phase.

Deliverables: implementation-plan.md and CLAUDE.md

CLAUDE.md is the file Claude Code reads automatically at the start of every session. Keep it short and have it point at everything else:

# CLAUDE.md
Read before doing anything: docs/prd.md, docs/screen-flow.md,
docs/tech-stack.md, docs/design-system.md, docs/backend-design.md,
docs/implementation-plan.md

## Rules
- Follow implementation-plan.md phase by phase.
- Use only the exact versions in tech-stack.md.
- Use only tokens and components from design-system.md.
- All authorization is enforced in the API, never only in Angular.
- If anything is not covered by the docs: STOP and ask me.
- Never commit secrets. Use dotnet user-secrets or environment
  variables. appsettings.Development.json is git-ignored.

## Layout
/api (ASP.NET Core)   /web (Angular)   /docs

## Phases
1. Scaffold + tooling   2. Auth + roles   3. Product catalogue
4. Cart + checkout     5. Orders + tracking   6. Polish + deploy

Step 7: The part you have to do yourself

Claude can't set up your machine or your accounts. Before building:

Install the .NET SDK, Node.js and PostgreSQL, and create an empty database for development
Put the database connection string and a long random JWT signing key into dotnet user-secrets (or environment variables), not into source files
Make sure appsettings.Development.json and any .env files are in .gitignore before your first commit
Never paste secrets into a chat

A word of caution: if you ever give Claude Code access to a production database, keep an eye on what it runs. For anything real, use a separate development database.

Step 8: Build it

Open the project in Claude Code and tell it your real-world constraints. Constraints are what keep an MVP small. Mine were a time limit and keeping login as simple as possible.

Implement the plan in CLAUDE.md, with these adjustments:
1. Use email and password login with ASP.NET Core Identity and JWT
   (no social or phone login).
2. Build the minimum version of each phase so we can finish in
   about 1 to 1.5 hours.
3. Read the database connection string and JWT key from user-secrets
   or environment variables. Use my local PostgreSQL, no Docker.
4. Work phase by phase. After each phase, tell me what to test and
   which commands to run (dotnet run, ng serve).
5. If a decision is not covered by the documents, stop and ask me.

Pay close attention to the first phase. If Claude Code follows your documents there, it will keep following them. If it drifts, fix the document and not just the code, otherwise the same mistake comes back in the next phase.

Step 9: Get a second opinion

The agent that wrote the code is a bad judge of it. So I ask Claude Code to spin up separate subagents, each with one narrow job and a fresh context.

Spawn four subagents to review the app independently:
1. UI/UX auditor: compare every Angular page to design-system.md
   and screen-flow.md (tokens, states, accessibility, responsive).
2. Code review auditor: structure of both the API and the Angular
   app, duplication, error handling, dead code, type safety,
   async/await and RxJS subscription leaks.
3. SQA: functional gaps against prd.md acceptance criteria, missing
   unit and end-to-end tests, edge cases.
4. Security reviewer: authorization policy gaps, insecure direct
   object access (can user A read user B's order?), JWT settings,
   CORS, input validation, exposed secrets, SQL injection and XSS.

Each agent reports findings by severity (critical, high, medium,
low) with file paths. Then give me one consolidated fix plan
ordered by priority. Do not change code yet.

Read the plan before anything gets changed. For an MVP, fixing the critical and high items is usually enough.

Step 10: Test it and ship it

First, a UAT (user acceptance testing) plan:

Write a User Acceptance Test (UAT) plan for this app. For each
role (Customer, Store Owner), list test cases with: ID, scenario,
preconditions, steps, expected result, and a pass/fail column.
Cover the happy path, validation errors, empty states, permission
checks and cancelling an order. Base it on prd.md and
screen-flow.md.

Then actually run it. Do it on your phone as well as your laptop, because mobile is where layout bugs hide.

Then the deployment guide:

Write a step-by-step guide to deploy this Angular + ASP.NET Core +
PostgreSQL app to Azure (App Service for the API, Static Web Apps
for Angular, Azure Database for PostgreSQL) and to AWS (for example
Elastic Beanstalk or App Runner for the API, S3 + CloudFront for
Angular, RDS for PostgreSQL). Include: connecting the Git
repository, CI/CD with GitHub Actions, environment variables and
secrets, running EF Core migrations safely, CORS settings, custom
domain and HTTPS, and a post-deploy smoke test checklist.

Two things people forget every time: updating the CORS settings so the deployed Angular URL can call the API, and running the EF Core migrations against the production database. If everything works locally but the deployed site shows network errors, check those first.

What I'd tell my past self

Let the AI interview you. Approving defaults is fast, and it surfaces decisions you didn't know you were making.
Keep one topic per document. A PRD isn't a schema, and a schema isn't a design system.
Pin versions and write down non-goals. Both shrink what the AI can guess at.
Tell it when to stop and ask. Silent guesses cause most of the rework.
Enforce authorization in the API, not just the UI. Ask a reviewer agent to try to break it.
When something's wrong, fix the document too, not only the code.
Keep the scope small. Cut features before you cut quality.

Wrapping up

AI-assisted development isn't really about typing less. It's about making your decisions early, in writing, so the build stops being a guessing game. Take the prompts above, swap QuickCart for your own idea, and read each document before you move to the next.

A Practical Guide to CLAUDE.md, Permissions, Plan Mode, Skills, and Sub-Agents

Naimul Karim — Thu, 05 Nov 2026 02:16:08 +0000

If your Claude Code routine is "type a feature request, hit enter, hope for the best," you're leaving most of the tool on the table. Typing build this feature works, but it's the shallowest way to use an agent that can read your repo, run your tests, and check its own work.

The difference between "I use AI to code" and "I work well with an AI agent" comes down to a handful of features: CLAUDE.md, permissions, plan mode, skills, and sub-agents. The trick is not to switch them all on at once. Each one earns its place when a real problem shows up. This post walks through them in the order you'd naturally need them.

First, what makes Claude Code different from chatting with Claude?

In a normal chat, you paste code in and paste answers out. Claude Code lives inside your project. It can read files, search the codebase, edit code, run terminal commands, use git, and run your tests to check whether its own change worked.

So instead of copying a service class into a chat window and explaining the surrounding system, you can say:

"Invoices can be marked as paid twice. Find out why and fix it."

and it will go hunting through the invoice and payment code on its own, change what needs changing, and run the tests.

Under the hood it follows a simple loop: gather context → take action → verify. Watch the tool calls scroll by (Read, Grep, Glob, Edit, Bash) and you'll know exactly what it's investigating. And if it's heading the wrong way, hit Esc and correct it mid-flight rather than waiting for the whole thing to finish.

A quick privacy note: "runs locally" doesn't mean nothing ever leaves your machine. Relevant file contents still get sent to the model so it can reason about them. If it's your employer's code, check the data policy of the account you're using.

Step 1: Give it a memory with CLAUDE.md (or AGENTS.md)

Close your session, come back tomorrow, and Claude has forgotten how you run the tests, that you chose Entity Framework Core, and that you already corrected it twice about the same thing. The fix is a markdown file at the root of your project that gets loaded at the start of every session.

Claude Code reads CLAUDE.md, and it now falls back to AGENTS.md if there isn't one, which is nice because that's the convention many other coding tools already use.

A few things worth knowing:

It's an attention budget. Everything in that file competes for space in the context window. Keep it lean. Under 200 lines is the usual advice, and 30 to 40 is even better.
Be specific, not inspirational. "Write clean code" tells Claude nothing. "Controllers live in src/Api/Controllers" and "run dotnet test before finishing" do.
Only include what Claude can't discover itself. It can see you use EF Core from the .csproj. It can't know that money is always stored as integer cents, or that every endpoint needs an authorization policy.
There are layers. Personal rules in your home .claude folder, shared project rules in the repo root, and a local file for your own sandbox URLs that stays out of git. Big monorepos can have nested files that only load for the area you're working in.
Start with /init, then actually read what it generates and trim it.
Keep it honest. A stale file that points to folders you moved is worse than no file at all.

One more concept that's easy to underestimate: context rot. Output quality can start slipping long before the window is full. A model with a 200k window might already show degradation around 50k tokens. So when you move to something unrelated, run /clear. Use /compact only when you're continuing the same work but want a smaller footprint. And /context shows you where your space is going.

Step 2: Control what it can do with permissions

Here's the catch with CLAUDE.md: it's guidance. If you write "never read the production settings file," Claude will probably obey, but nothing technically stops it. For hard boundaries you need permissions, which the tool itself enforces.

There are three rule types, checked in the order deny → ask → allow:

{
  "permissions": {
    "allow": ["Bash(dotnet build)", "Bash(dotnet test)", "Bash(git status)"],
    "ask": ["Bash(git push:*)", "Bash(dotnet ef database update:*)"],
    "deny": ["Read(./**/appsettings.Production.json)", "Read(./**/secrets.json)"]
  }
}

Save that as .claude/settings.json and you've got a sensible baseline: routine builds and tests run without nagging you, pushes and database updates always need your approval, and production config is off limits.

Then test it. Drop a dummy appsettings.Production.json into the project, ask Claude to read it, and confirm the request gets refused. Claude should tell you the read was blocked instead of hunting for a workaround. Don't assume a rule works just because you wrote it.

You'll also meet different modes along the way (manual, auto-edit, plan, auto), which you can cycle through with Shift+Tab. Manual is great while you're learning what Claude does. Once you trust the setup, a more automatic mode removes the boring prompts. The goal isn't zero prompts. It's zero pointless prompts, while keeping a human in the loop for things that matter.

One habit worth building: put real connection strings into user secrets or environment variables yourself. Never paste them into the chat.

Step 3: Use plan mode when the decision is expensive

Early features like a new endpoint or a UI tweak are easy to review and easy to undo. If you don't like the result, you change it. A database schema is a different animal. Migrations, relationships, and how something like invoice status is represented are costly to rework once code is built on top of them.

That's what plan mode is for. Claude can read, search and research, but it can't touch your source until you approve a plan. Imagine asking for a PostgreSQL + Entity Framework Core setup with only customers, invoices and line items, and explicitly ruling out recurring billing, tax rules and multi-currency for now. Claude would spin up an exploring sub-agent, ask a few clarifying questions (should payment status be stored or derived from payments? where do line items live?), and come back with a plan.

The lesson that matters most: read the plan. Approving without reading gains you nothing. A weak plan says "add database, add invoices, update API." A good one names tables, relationships, files to change, the migration approach, and how it'll verify the result. You can even open it in an editor with Ctrl+G and edit it directly.

Catching "you're over-engineering this" in the plan takes seconds. Catching it after the entities, migrations and API changes exist takes a lot longer.

Two other pointers:

Don't use plan mode for everything. Changing a heading doesn't need a ceremony.
After a big decision, update CLAUDE.md with only the conventions future sessions need to remember, such as the migration command and where entity configurations live.

Step 4: Turn repeated processes into skills

By the time you've added a handful of API endpoints, you notice you keep saying the same things: look at how existing controllers are structured, reuse the validation and error-handling patterns, write tests alongside, verify when done. Pasting that checklist into every prompt gets old.

A skill is a folder with a SKILL.md that Claude loads only when relevant. The rule of thumb is simple:

Project fact ("run tests with dotnet test", "use Entity Framework Core for data access") → CLAUDE.md
Repeatable process ("inspect, reuse, build, verify") → a skill
One-off task → just ask

---
name: add-endpoint
description: Add or modify a REST API endpoint following the project's controller, validation, error-handling and testing conventions. Use when creating a new endpoint or significantly changing an existing one.
---

Add or update the following endpoint: $ARGUMENTS

1. Inspect an existing, similar endpoint and its tests first.
2. Reuse the existing request/response models, validators and error format.
3. Keep business logic in the service layer, not the controller.
4. Add unit and integration tests, run `dotnet test`, then summarize.

The description is the most important line. Claude uses it to decide whether the skill applies. A vague one means it won't trigger when you expect it to.

After that, something like /add-endpoint GET /invoices/{id}/pdf gives you a result that matches your existing code, and /add-endpoint POST /customers follows right after with the same process. Same workflow, different feature.

A few more skill tips:

Skills load in layers (metadata first, then the main file, then extra reference files only when needed), which keeps your context light.
For anything with side effects, like deploy or commit, you can disable automatic invocation so only you can trigger it.
Don't hoard them. Every skill adds metadata Claude has to consider.
Read third-party skills and plugins before installing. They can contain scripts and tool access.
Don't try to write the perfect skill on day one. Use it, notice where Claude still slips, then sharpen it.

Library maintainers and vendors can ship their own skills and plugins too. A skill is one reusable process, while a plugin is a package that can bundle skills plus other capabilities such as MCP servers.

Step 5: Hand off investigations to sub-agents

Eventually the codebase is big enough that, before building something like an audit log, Claude would need to understand your entities, how the current user flows through a request, background jobs, error handling and the test setup. If it researches all of that in your main conversation, every file read and search result piles up in the same context you need for the actual build.

A sub-agent is a separate Claude instance with its own context window. It takes a focused task, explores, and reports back only the useful findings. That's the entire value: context isolation. It's not a smarter Claude, and it doesn't gain expertise from a fancy job title. "Senior staff elite security architect" is just decoration. The useful question is: what work can happen separately that my main conversation doesn't need to carry?

For the audit-log idea, you could ask for five independent investigations, with an explicit "don't implement anything yet":

The entity model and DbContext
How authentication and the current user identity are resolved
Existing background jobs
The logging and error-handling middleware
The test fixtures and conventions

None of these depend on each other, so they can run in parallel and come back as one combined summary. That's usually faster than a single agent working through them one after another, and your main context only receives the conclusions.

Claude Code also has built-in agent types such as Explore (read-only investigation), Plan, and a general-purpose one. You don't have to call anything special. Just tell Claude what to delegate.

Afterward, scope the first version tightly: record who changed what and when for create, update and delete on invoices, and nothing else yet, so no retention policies, search UI or export. And remember that identity must come from the server. The user ID in an audit entry should be taken from the authenticated principal, never from a value the client sends. That's exactly the sort of thing to verify in the plan.

Step 6: Spawn a sub-agent to review the code

Sub-agents aren't only for research. One of the most useful jobs you can give one is reviewing what the main session just wrote.

Why not just ask the same session to "check your work"? Because it's carrying the whole conversation: every assumption, every shortcut, every reason it chose approach A over B. It tends to agree with its own decisions. A fresh sub-agent starts with a clean context and sees the diff the way a new teammate would, with no attachment to how it got there.

You can do it with a plain prompt:

"Spawn a sub-agent to review the changes on this branch against main. It should check correctness and edge cases, security (authorization, input validation, secrets in logs), missing tests, and whether the code follows the conventions in CLAUDE.md. It must not modify any files. Return findings grouped by severity, with file and line references."

If you do this often, define a reusable reviewer in .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code changes for bugs, security issues, missing tests and convention violations. Use after finishing a feature or before opening a pull request.
tools: Read, Grep, Glob, Bash
---

You are a careful code reviewer. Review the current branch's diff against main.

Focus on:
- Logic errors and unhandled edge cases
- Authorization gaps and unvalidated input
- N+1 queries and missing transactions in data access
- Missing or weak tests
- Violations of the conventions in CLAUDE.md

Do not edit files. Report findings by severity (high, medium, low) with file and line,
a one-sentence explanation of the risk, and a suggested fix.

Notice the tools line. A reviewer shouldn't be able to edit anything, so you leave out Edit and Write. That's a small guardrail that keeps the agent doing exactly one job.

Triage before you fix

The findings come back, and the temptation is to say "fix everything." Don't. For each one, decide whether it's real, whether it's relevant, and whether it's worth fixing now:

Verify first. Ask Claude to confirm the finding against your actual code and explain the risk in the context of this app, without changing anything. Reviewers can be wrong, or flag a problem that doesn't apply to your setup.
Fix now what is real and cheap, especially anything touching auth, data access or money.
Write down for later what is real but out of scope. A low-severity finding whose proper fix needs a whole new subsystem shouldn't hijack the current task.
Never silently ignore a finding. "Not now" is fine. "Never looked at it" isn't.

A reviewer sub-agent doesn't replace your own review, and it isn't a substitute for dedicated security tooling on sensitive areas like authentication or payments. Think of it as a second pair of eyes that happens to be cheap and fast. You're still the one who decides.

The progression that matters

Looking back, the arc is worth remembering:

Start in an empty folder and give Claude a small, bounded task.
Add project context (CLAUDE.md) once you're tired of repeating yourself.
Add permissions when approval prompts get annoying or secrets need protecting.
Use plan mode when decisions become expensive to reverse.
Write skills when you spot a repeating process.
Use sub-agents when investigation starts crowding your main context.
Use a separate reviewer sub-agent before you trust what was just written.

Don't switch everything on at once. Let the problem you have create the reason to use the feature.

Key take aways

Give Claude good context, keep tasks small, and review what it does.
Test your guardrails instead of assuming they work.
The cheapest place to fix a bad decision is the plan.
Have a fresh sub-agent review what the main session wrote, then triage the findings instead of auto-fixing them.
Keep your project instructions current, and delete stale ones.
Give it more freedom gradually, as you learn how it behaves on your projects.

Beyond these sit parallel agents on isolated git worktrees, external tools through MCP, and hooks that automate checks. Those are next on my list.

Building Modern Scalable Applications: Understanding Docker, Kubernetes, Redis, Kafka & Prometheus

Naimul Karim — Thu, 05 Nov 2026 01:57:35 +0000

A customer opens an online store, browses a product, and clicks Place Order.

From the customer's perspective, it is a simple interaction. Behind the scenes, however, several components may work together: containers run the application, orchestration platforms manage those containers, databases store information, caches improve response times, queues handle background work, and monitoring tools help engineers understand what is happening in production.

The interesting part is not memorizing the names of these technologies. It is understanding which problem each one solves, how they connect, and what trade-offs they introduce.

Let's follow one order through a typical online application and explore the technologies along the way.

The architecture in this article is an illustrative example, not a required stack. A real application should use only the components that solve problems it actually has.

1. Docker: Package the application consistently

A familiar problem for developers is:

It works on my machine, but it doesn't work in production.

An application may run with one runtime version on a developer's laptop, while the production server has another. A dependency may be missing, or a library version may be different.

Docker helps reduce this environment mismatch by packaging an application and its required runtime dependencies into an image.

A useful way to think about the two main terms:

Image: the packaged template.
Container: a running instance created from that image.

The same image can be used in development, testing, staging, and production, helping those environments behave more consistently.

There is an important qualification: a container image does not make every machine identical. CPU architecture and operating-system compatibility still matter. For example, an image built for one processor architecture may not run natively on a machine with another architecture. Multi-platform image builds can address this when needed.

Docker solves the packaging problem. It does not, by itself, manage a fleet of containers.

2. ECS and Kubernetes: Run and manage containers

Once an application is containerized, we need a way to run it, scale it, recover from failures, and manage its deployment.

Two common options are Amazon ECS and Kubernetes.

Amazon ECS

If an organization is already using AWS, Amazon Elastic Container Service (ECS) can be a practical choice. It is an AWS-managed container orchestration service, and AWS handles much of the underlying orchestration infrastructure.

Kubernetes

Kubernetes is an open-source container orchestration platform. It can run across different cloud providers and in on-premises environments, offering flexibility and control.

That flexibility comes with operational responsibility. A managed Kubernetes service such as Amazon EKS or Google Kubernetes Engine manages important parts of the control plane, but teams still need to understand and manage areas such as worker nodes, networking, add-ons, workloads, and cluster configuration.

So which one is better?

Neither is universally better. The right choice depends on the team's needs and operational capacity:

A smaller team operating primarily on AWS may prefer ECS for its simpler operational model.
A team that needs Kubernetes portability, its ecosystem, or more control over orchestration may choose Kubernetes.

The key question is not which tool is more popular. It is how much complexity the team is prepared to operate.

3. Terraform: Define infrastructure as code

Containers need infrastructure: compute resources, networks, access rules, databases, and other cloud resources.

One approach is to create these resources manually through a cloud console. The problem appears when the same setup must be repeated for development, staging, and production.

Over time, environments can become different. Someone changes a security rule in staging but forgets to make the corresponding change in production. A bug then appears in production but cannot be reproduced in staging.

This is known as configuration drift.

Terraform addresses this by allowing infrastructure to be described as code.

Instead of relying on a sequence of manual console operations, teams define resources in configuration files and keep those files in version control.

That brings several benefits:

Infrastructure changes can be reviewed through pull requests.
Environments can be created more consistently.
Git history helps explain what changed and when.
Rebuilding an environment becomes more repeatable.

Infrastructure as code does not eliminate the need for careful review. A reviewed configuration can still contain a mistake. It does, however, make infrastructure changes more visible, repeatable, and manageable.

4. DNS and load balancing: Route incoming requests

Now imagine the application is deployed and a customer opens shop.com.

The browser needs to find the server responsible for that domain. This is where DNS (Domain Name System) comes in: it resolves a domain name to the information needed to reach the service, commonly an IP address.

The request then reaches a load balancer.

A production application may run across multiple backend instances rather than on one server. The load balancer distributes incoming requests among those instances.

It can also perform health checks. If an instance stops responding or fails its health check, the load balancer can stop sending new traffic to it and route requests to healthy instances instead.

This helps improve availability and prevents one server from becoming the only point handling all incoming traffic.

5. PostgreSQL: Store the source-of-truth data

The backend receives the order request, validates it, and saves the order.

A relational database such as PostgreSQL can store the application's core business data:

Customers
Products
Orders
Payments and order status
Other related records

For many applications, the relational database is the authoritative source of truth.

But as traffic grows, repeatedly running the same database queries can become expensive. A popular product page, for example, might be requested thousands of times.

That leads to the next component.

6. Redis: Reduce repeated database work with caching

Redis is commonly used as an in-memory data store and cache.

Suppose many customers open the same product page. If every request reads the same product information from PostgreSQL, the database has to repeat work that may not need to be repeated.

A cache can help:

The application checks Redis for the product data.
If the data is present, the application returns it from the cache.
If it is missing, the application reads it from PostgreSQL.
The application can then place a copy in Redis for later requests.

This is a common cache-aside pattern.

Redis does not automatically replace the main database. PostgreSQL can remain the source of truth while Redis stores temporary or reusable copies.

The challenge: cache invalidation

What happens if a product's price changes in PostgreSQL while Redis still contains the old price?

The application could return stale information.

The cache therefore needs an invalidation or update strategy. Depending on the use case, that might involve deleting the cached entry, updating it after a database change, or allowing it to expire after a defined time.

Caching can improve performance, but it introduces a consistency problem that needs to be designed deliberately.

7. OpenSearch: Handle more advanced search requirements

A customer searches for wireless headphones. They might make a typo, use a slightly different phrase, or expect the most relevant products to appear first.

A relational database can support text search, but more advanced requirements—such as relevance ranking, typo tolerance, and large-scale search—may call for a dedicated search engine.

OpenSearch is designed for search and analytics use cases.

An application can index its product catalog in OpenSearch and use it to handle product-search queries. PostgreSQL can still remain the authoritative source of product data.

This distinction matters:

PostgreSQL stores the core business records.
OpenSearch provides search capabilities over indexed data.

The search index is typically a derived representation of the source data, so the application needs a process to keep it reasonably up to date.

A dedicated search engine is useful when the product's search requirements justify the extra infrastructure. It is not something every application needs from day one.

8. Amazon S3: Store files outside the relational database

Product images and profile photos are files, not ordinary relational records.

Amazon S3 is an object storage service designed to store files and other unstructured data.

A typical flow looks like this:

The application uploads an image to S3.
S3 stores the object.
The application stores the object's key or reference in PostgreSQL.
When the image is needed, the application or browser retrieves it from S3, subject to the configured access controls.

This separates responsibilities:

PostgreSQL stores business data and file references.
S3 stores the actual file objects.

The file reference should not be treated as automatically public. Access can be controlled using bucket policies, application authorization, or time-limited pre-signed URLs, depending on the design.

9. Message queues: Move slow work out of the request

Saving an order may trigger several additional tasks:

Send an order confirmation email.
Generate an invoice.
Notify the warehouse.
Record an analytics event.

Should the customer wait for every task to finish before receiving a response?

Usually, that would make the request slower than necessary.

A message queue allows the backend to place work onto a queue and return a response without waiting for every background task to complete. Background workers consume the messages and perform the work independently.

Common options include Amazon SQS and RabbitMQ.

Acknowledgements and retries

A worker generally acknowledges a message after successfully processing it. If the worker crashes before acknowledging it, the queue may make the message available for processing again.

That means a message can sometimes be delivered more than once.

Workers should therefore be designed to handle duplicate delivery safely. This is called idempotency: processing the same operation more than once should not produce an unintended duplicate effect.

For example, an email worker could record that a confirmation has already been sent for a particular order and avoid sending it again when the same message is retried.

Queues improve responsiveness and decouple background work from the main request, but they introduce concerns such as retries, duplicate messages, failure handling, and monitoring.

10. Kafka: Distribute events to multiple consumers

A queue is useful when an application needs to hand off tasks to background workers. But sometimes an event needs to be made available to several independent systems.

For example, when an order is placed, different consumers may need to react:

An analytics service records the purchase.
An inventory service updates stock.
A notification service sends a message.
A reporting pipeline processes the event.

Apache Kafka is a distributed event-streaming platform that can support this kind of event-driven architecture.

Rather than thinking of every event as a one-time task handed to a single worker, Kafka lets producers publish events to topics. Multiple consumer applications can read those events independently, according to their own processing needs.

Kafka is especially useful when event volume, independent consumers, replay, or durable event streams are important requirements.

It is not automatically a replacement for every queue. A simpler queue may be easier to operate when the requirement is simply to distribute background tasks. Choose based on the messaging problem, not just the technology's popularity.

11. CI/CD and Amazon ECR: Deliver code changes reliably

The application is running, but developers continue to fix bugs and add features. How does a code change reach production?

With a manual deployment process, someone might connect to each server, pull the latest code, and restart the application. If one server is missed, different instances may run different versions.

A CI/CD pipeline automates much of this delivery process.

A typical container-based pipeline might:

Start when a developer pushes code.
Build the application and run automated tests.
Build a Docker image if the required checks pass.
Push the image to a container registry.
Deploy the selected image version to the target environment.

On AWS, Amazon Elastic Container Registry (ECR) can store Docker and other OCI container images.

Think of ECR as a registry for container images: it stores the packaged application versions that deployment systems can pull.

CI/CD makes delivery more repeatable, but the quality of the pipeline still depends on the checks, approvals, and deployment safeguards configured by the team.

12. Helm: Manage Kubernetes application configuration

When deploying to Kubernetes, teams need configuration describing how an application should run.

Development, staging, and production may share most of the same deployment structure while differing in image tags, replica counts, resource limits, or environment-specific settings.

Maintaining separate copies of nearly identical configuration files can lead to drift.

Helm helps manage Kubernetes applications through charts and configurable values.

A chart defines reusable Kubernetes templates. Different values files can provide environment-specific settings.

This reduces duplication and makes it easier to keep deployment configuration consistent across environments.

Helm is a Kubernetes package manager; it does not replace Kubernetes itself. It helps organize and render the configuration that Kubernetes uses.

13. Argo CD: Use GitOps to keep deployments aligned

Argo CD is a declarative GitOps continuous delivery tool for Kubernetes.

The central idea behind GitOps is that the desired state of the application and cluster configuration is stored in Git.

Argo CD watches the configured Git repository and compares the desired state there with the state currently running in the Kubernetes cluster.

If they differ, Argo CD can report the difference and, depending on the configured synchronization policy, apply the desired configuration.

For example, if someone manually changes a deployment in the cluster, Argo CD can detect that the live state no longer matches the configuration in Git. With automated synchronization and self-healing configured, it can bring the cluster back toward the declared state.

This gives teams a traceable workflow:

Configuration changes are committed to Git.
Changes can be reviewed.
The cluster is reconciled against the declared configuration.
Git history provides a record of changes and supports rollback workflows.

GitOps does not make every deployment safe automatically. If an incorrect configuration is merged, the system may faithfully deploy that incorrect configuration. Reviews, tests, and rollout safeguards remain important.

14. Prometheus and Grafana: Understand application health

The application is live. Then an order endpoint that normally responds in one second starts taking five seconds.

Where should the team look?

Prometheus is a monitoring system that collects and stores metrics. Applications and infrastructure can expose measurements such as:

Request count
Request latency
Error rate
CPU and memory usage
Queue depth

Prometheus commonly uses a pull-based model: it periodically scrapes metrics from configured targets.

If a target becomes unavailable, Prometheus can report that it is no longer being scraped successfully. That signal can help teams detect failures.

Grafana is commonly used to visualize metrics through dashboards. Engineers can inspect trends, identify when a latency spike began, and compare measurements across services.

Metrics are useful for showing that something is wrong. But a graph showing that an endpoint is slow may not explain which dependency caused the delay.

That is where tracing becomes useful.

15. OpenTelemetry: Instrument and follow requests across services

In a distributed application, one customer request may travel through several components:

The order service receives the request.
It calls the inventory service.
The inventory service calls another dependency.
The order service communicates with a payment service or external API.

If the overall request takes five seconds, which step consumed the time?

Distributed tracing follows a request as it moves across services. A trace is made up of spans, which represent timed operations and their relationships. Looking at those spans helps engineers identify where time was spent.

OpenTelemetry provides vendor-neutral APIs, SDKs, and instrumentation for generating and collecting telemetry, including traces, metrics, and logs.

An application needs to be instrumented for useful telemetry to appear. That can involve adding SDK instrumentation to the code or using supported automatic instrumentation.

The OpenTelemetry Collector can receive, process, and export telemetry to compatible observability backends.

One important point: installing OpenTelemetry alone does not magically reveal application behavior. The application and its dependencies must produce telemetry, and the collection and export pipeline must be configured.

Prometheus, Grafana, and OpenTelemetry serve related but different roles:

Prometheus: collects and stores metrics.
Grafana: visualizes metrics and other supported telemetry sources.
OpenTelemetry: provides instrumentation and a standard way to generate, collect, and export telemetry.

Together, these tools help teams move from noticing a performance problem to investigating its cause.

16. Bringing the pieces together

Let's revisit the customer's order and group the technologies by the problems they solve.

Area	Technologies	Main responsibility
Application packaging	Docker	Package the application and its dependencies
Container orchestration	ECS or Kubernetes	Run and manage containers
Infrastructure	Terraform	Define and provision infrastructure as code
Request routing	DNS and load balancer	Resolve the service address and distribute traffic
Primary data	PostgreSQL	Store core business records
Caching	Redis	Reduce repeated reads and improve response times
Search	OpenSearch	Support advanced search and relevance
File storage	Amazon S3	Store images and other objects
Background processing	SQS or RabbitMQ	Decouple asynchronous tasks from requests
Event streaming	Kafka	Distribute event streams to independent consumers
Delivery	CI/CD and ECR	Test, package, store, and deliver application versions
Kubernetes configuration	Helm	Template and manage Kubernetes application configuration
GitOps deployment	Argo CD	Reconcile cluster state with configuration in Git
Monitoring and observability	Prometheus, Grafana, OpenTelemetry	Collect, visualize, and investigate telemetry

A simplified flow looks like this:

                         DEVELOPER WORKFLOW
                                  |
                           Code pushed to Git
                                  |
                              CI/CD
                         Build + test + image
                                  |
                             Amazon ECR
                                  |
                       Helm configuration in Git
                                  |
                               Argo CD
                                  |
                         ECS / Kubernetes
                                  |
                            Docker images
                                  |
CUSTOMER --> DNS --> LOAD BALANCER --> BACKEND APPLICATION
                                      |
                +---------------------+----------------------+
                |                     |                      |
            PostgreSQL              Redis                OpenSearch
          source of truth           cache              product search
                |
          File references
                |
             Amazon S3

       Order created --> Queue --> Background workers
              |
              +------> Kafka events --> Independent consumers

        Prometheus --> Metrics
        Grafana ----> Dashboards
        OpenTelemetry --> Traces, metrics, and logs

This is a conceptual view. The exact deployment and telemetry architecture will vary by application and cloud environment.

17. Every technology solves a problem—and adds responsibility

It is tempting to think that adding more tools automatically makes an application more scalable. In reality, every new component introduces operational and design trade-offs.

Consider a few examples:

Redis can reduce database load, but cached data can become stale.
Queues keep slow work out of the request path, but messages may be retried or delivered more than once.
Kafka supports durable event streams and multiple consumers, but it adds operational and architectural complexity.
Kubernetes provides orchestration flexibility, but teams must manage more of the platform.
Argo CD can reconcile a cluster to Git, but it can also apply a bad configuration if that configuration is approved and committed.
OpenSearch improves search capabilities, but the search index must be maintained alongside the source data.

This leads to a more useful way to evaluate technology:

What concrete problem are we trying to solve?
Is the problem significant enough to justify another component?
What new failure modes and operational responsibilities will this introduce?
Can the team support and monitor it?
Is there a simpler solution that is sufficient?

Conclusion

A scalable application is not built by collecting as many technologies as possible.

Docker, Kubernetes, Terraform, PostgreSQL, Redis, Kafka, Prometheus, and the other tools discussed here each address different concerns. Their value comes from how well they fit the application's actual requirements and how thoughtfully they are operated together.

Start with the simplest architecture that meets the need. Add caching when repeated reads become a bottleneck. Add queues when background work slows down user requests. Introduce a dedicated search engine when search requirements outgrow the database's capabilities. Adopt orchestration and GitOps practices when deployment complexity justifies them.

System design is not about remembering a list of tools. It is about understanding the problem that makes each tool worth introducing—and the trade-offs that come with it.

How to Debug Android Chrome Browser Logs from a Windows Laptop

Naimul Karim — Mon, 17 Aug 2026 23:02:26 +0000

Testing a website on a real Android device is often necessary when a problem cannot be reproduced in desktop Chrome or Chrome's device emulation.

Chrome's Remote Debugging feature allows you to connect an Android phone to a Windows laptop and inspect the mobile Chrome tab using desktop Chrome DevTools.

With this setup, you can inspect:

JavaScript console logs and errors
Network requests and API responses
Request and response headers
HTML and CSS
Cookies and browser storage
JavaScript source code
Breakpoints and debugging
Authentication and browser-specific issues

This guide covers the complete setup, including troubleshooting the common Pending authentication and unauthorized ADB errors.

Part 1: Set Up Android Remote Debugging

Step 1: Enable Developer Options on Android

Android hides Developer Options by default.

The exact steps can vary by manufacturer.

Google Pixel

Go to:

Settings → About phone → Build number

Tap Build number seven times.

You may be asked to enter your phone PIN.

Android should display a message indicating that Developer Options have been enabled.

Other Android Devices

The location can vary between Samsung, OnePlus, Xiaomi, Motorola, and other manufacturers.

If you cannot find it, search Android Settings for:

Build number

Step 2: Enable USB Debugging

On a Google Pixel, go to:

Settings → System → Developer options

Find:

USB debugging

Turn it on and confirm the warning when Android asks.

USB debugging allows the Windows computer to communicate with the Android device through ADB.

Step 3: Connect the Android Phone to Windows

Connect your Android phone to your Windows laptop using a USB data cable.

Make sure the cable supports data transfer, not just charging.

Keep the phone unlocked

This is important because Android may need to display the USB debugging authorization prompt.

Windows may display a notification such as:

Choose what to do with this device

You can close this notification.

This is a Windows AutoPlay notification, not the Android USB debugging authorization prompt.

If necessary, open the USB notification on Android and select:

File transfer / Android Auto

Step 4: Authorize USB Debugging

After connecting the phone, Android should display:

Allow USB debugging?

The dialog will also display the computer's RSA key fingerprint.

Select:

Always allow from this computer

Then tap:

Allow

This authorizes the Windows computer to communicate with your Android device through ADB.

Part 2: Open the Website on Android Chrome

Step 5: Open Chrome on the Android Device

On your Android phone:

Open Chrome.
Navigate to the website you want to test.
Leave the website tab open.

The page you want to debug must be running in Chrome on the Android phone.

Part 3: Connect Chrome DevTools

Step 6: Open Chrome Remote Debugging on Windows

On your Windows laptop, open Chrome and navigate to:

chrome://inspect/#devices

Make sure this option is enabled:

Discover USB devices

Your Android device should appear on the page.

Under the device, Chrome should display the Chrome tabs currently open on your Android phone.

You should see something similar to:

Android Device
    Chrome
        https://example.com
        inspect

Find the website you want to debug and click:

Inspect

Part 4: Debug the Android Website

Chrome DevTools will now open on your Windows laptop.

Although DevTools is running on Windows, it is connected to the webpage running on the physical Android device.

Console

Use the Console tab to inspect:

console.log() output
JavaScript errors
Warnings
Uncaught exceptions
Runtime errors

Network

Use the Network tab to inspect:

API requests
HTTP status codes
Request payloads
Response bodies
Request headers
Response headers
Request timing
Failed requests

Example: Login works on desktop but fails on Android

Open Network.
Perform the login on the Android phone.
Find the login/API request.
Open the request.
Inspect:
- Headers
- Payload
- Response
- Status Code

You can now see what the physical Android browser actually sent and received.

Part 5: Troubleshooting `Pending authentication`

Sometimes chrome://inspect/#devices detects the Android phone but cannot establish the debugging connection.

You may see:

Device information is stale.
Offline
#DEVICE_SERIAL
Pending authentication: please accept debugging session on the device.

At the same time, the phone may indicate that USB debugging is connected.

This usually means:

Windows can detect the Android device, but the ADB authorization handshake has not completed successfully.

The easiest way to troubleshoot this is to reset the ADB authorization.

Step 1: Install Android Platform Tools

Download SDK Platform-Tools for Windows from Google's Android developer website:

https://developer.android.com/tools/releases/platform-tools

Extract the downloaded ZIP file.

Inside the extracted platform-tools directory, you should see files such as:

adb.exe
fastboot.exe

The adb.exe executable is what we will use to check and manage the Android connection.

Step 2: Open Command Prompt in `platform-tools`

Open the extracted platform-tools directory in Windows File Explorer.

Click the File Explorer address bar.

Type:

cmd

Press Enter.

Command Prompt should open directly in the platform-tools directory.

For example:

C:\Users\YourName\Downloads\platform-tools>

This allows you to run ADB commands without adding ADB to the Windows PATH.

Step 3: Check the ADB Connection

Run:

adb devices

If authorization has not completed, you may see:

List of devices attached
DEVICE_SERIAL    unauthorized

The important part is:

unauthorized

This means:

Windows can see the Android device.
ADB can detect the device.
The Android device has not authorized this computer.

Step 4: Reset USB Debugging Authorization

On your Android phone, go to:

Settings → System → Developer options

Select:

Revoke USB debugging authorizations

Confirm the action.

Then turn:

USB debugging → Off

Step 5: Restart the ADB Server

On Windows, run:

adb kill-server

Disconnect the USB cable from the phone.

Then:

Turn USB debugging back on.
Reconnect the USB cable.
Keep the phone unlocked.

Start ADB again:

adb start-server

You may see:

* daemon not running; starting now at tcp:5037
* daemon started successfully

Then check the device:

adb devices

Step 6: Accept the Android Authorization Prompt

Look at your Android phone.

You should now receive:

Allow USB debugging?

Select:

Always allow from this computer

Then tap:

Allow

This is the critical step.

If the authorization dialog does not appear, keep the phone unlocked and try disconnecting and reconnecting the USB cable.

Step 7: Verify ADB Authorization

Run:

adb devices

Before authorization

You may see:

List of devices attached
DEVICE_SERIAL    unauthorized

After successful authorization

You should see:

List of devices attached
DEVICE_SERIAL    device

The important change is:

unauthorized

to:

device

This confirms that ADB authorization has succeeded.

Step 8: Return to Chrome Remote Debugging

On Windows, refresh:

chrome://inspect/#devices

The Pending authentication message should disappear.

Now:

Open Chrome on the Android phone.
Navigate to the website you want to test.
Keep the tab open.
Refresh chrome://inspect/#devices on Windows.
Find the Android Chrome tab.
Click Inspect.

You can now use Chrome DevTools normally.

Quick Troubleshooting Checklist

If your Android Chrome tab does not appear:

[ ] Developer Options are enabled.
[ ] USB debugging is enabled.
[ ] The Android phone is unlocked.
[ ] The USB cable supports data transfer.
[ ] The phone is connected using File transfer / Android Auto if necessary.
[ ] Discover USB devices is enabled in chrome://inspect/#devices.
[ ] adb devices detects the phone.
[ ] The phone is not shown as unauthorized.
[ ] You accepted Allow USB debugging? on the phone.
[ ] adb devices reports the device as device.
[ ] The website is open in Chrome on the Android phone.
[ ] You refreshed chrome://inspect/#devices.

The Complete Flow

Once everything is working, the debugging flow looks like this:

Android Chrome
      ↓
USB Debugging
      ↓
ADB
      ↓
Windows Laptop
      ↓
chrome://inspect/#devices
      ↓
Chrome DevTools
      ↓
Console / Network / Elements / Application / Sources

The important distinction is that the website runs on the physical Android device, while the DevTools interface runs on your Windows laptop.

Why Use a Real Android Device?

Chrome's desktop device emulation is useful, but it cannot reproduce every behavior of a physical Android device.

Remote debugging is especially useful for investigating:

Mobile-only JavaScript errors
Authentication problems
API failures
Cookie and storage issues
Browser-specific behavior
Responsive UI problems
Touch-related issues
Network problems
Mobile Chrome rendering issues
Problems that cannot be reproduced using desktop Chrome

When an issue occurs only on a real Android phone, remote debugging gives you direct access to the browser's Console, Network, Elements, Application, and Sources tools while the application is running on the actual device.

Conclusion

Connecting a real Android device to Chrome DevTools is straightforward once ADB authorization is working.

The normal flow is:

Enable Developer Options
        ↓
Enable USB Debugging
        ↓
Connect Android to Windows
        ↓
Authorize the Computer
        ↓
Open Chrome on Android
        ↓
chrome://inspect/#devices
        ↓
Click Inspect
        ↓
Debug with Chrome DevTools

If Chrome shows:

Pending authentication

and ADB shows:

unauthorized

the key is to reset USB debugging authorization, restart ADB, reconnect the phone, and accept the authorization prompt on Android.

Once adb devices changes from:

unauthorized

to:

device

Chrome Remote Debugging should be able to establish the connection.

Stop Prompt Engineering, Start Context Engineering

Naimul Karim — Mon, 03 Aug 2026 04:32:35 +0000

AI agents get talked about a lot, but most explanations stay abstract. Here's a short, practical breakdown of what actually makes an agent work — plus a simple example.

Chat vs. Agent

Chat model → question → answer (you do the work)
Agent → goal → result (it plans + executes for you)

Chat:   You ask ──> Model answers ──> You act
Agent:  You set goal ──> Agent plans → acts → checks ──> Result delivered

The Agent Loop

Every agent — no matter the platform — runs the same loop:

   ┌─────────┐
   │ OBSERVE │  read context, current state
   └────┬────┘
        ▼
   ┌─────────┐
   │  THINK  │  decide next action
   └────┬────┘
        ▼
   ┌─────────┐
   │   ACT   │  execute, then loop again
   └────┬────┘
        │
        └──────► repeats until task is done

An agent = LLM (brain) + Loop + Tools + Context. The "harness" (Claude Code, Cowork, Codex, etc.) is just the app that runs this loop.

The Stack, in Layers

┌────────────────────────────┐
│ 5. Skills   → reusable SOPs │
├────────────────────────────┤
│ 4. Tools    → via MCP       │
├────────────────────────────┤
│ 3. Memory   → memory.md     │
├────────────────────────────┤
│ 2. Context  → agents.md     │
├────────────────────────────┤
│ 1. Loop     → observe→think→act │
└────────────────────────────┘

Context file (agents.md / Claude.md) — persistent "system prompt" with your role, business, tools, and preferences. Loaded every session.
Memory (memory.md) — updated whenever the agent is corrected. Compounds over time.
Tools (MCP) — Model Context Protocol connects the agent to Gmail, Notion, Calendar, Stripe, etc. without custom integration work per tool.
Skills — a markdown file documenting a repeatable process once, so it never needs re-explaining. Can be chained or scheduled.

Prompt engineering → Context engineering. Rich context turns a 2-word prompt into a great result.

A Quick Example

A solo creator automating their weekly newsletter:

agents.md — newsletter's audience, tone, format, connected tools (Notion, Docs, social)
memory.md — learns preferences over time ("shorter subject lines," etc.)
Connect Notion + Docs + social via MCP
One prompt: "Pull this week's notes, draft the issue, write a companion thread."
Package it as a weekly-newsletter skill → schedule it for every Thursday

Same shape every time: context + memory + tools set up once → simple prompts → consistent results.

Starter Checklist

[ ] Pick a simple harness, create a project folder
[ ] Write agents.md (role, business, tools, preferences)
[ ] Add a starter memory.md
[ ] Connect 2–3 high-value tools via MCP
[ ] Run a real task, watch the loop work
[ ] Turn a repeatable task into a skill
[ ] Schedule a recurring skill
[ ] Repeat for another role/project

This isn't about cleverer prompts — it's front-loading context once so every future ask can stay simple.

AI Agentic Workflow Explained: A Quick Tour of Harness, Tools, Skills, MCP, and Memory

Naimul Karim — Wed, 22 Jul 2026 04:35:27 +0000

AI applications are moving beyond simple chat experiences.

The next generation of AI systems are AI agents — systems that can understand goals, reason about problems, use external tools, access enterprise data, and complete multi-step workflows.

However, an AI agent is not just a Large Language Model (LLM) with a prompt.

A production AI agent is a combination of multiple components working together:

AI Agent
   |
   +-- Model
   |
   +-- Harness
   |
   +-- Tools
   |
   +-- MCP Integrations
   |
   +-- AGENTS.md
   |
   +-- Skills
   |
   +-- Memory

The model provides intelligence and reasoning.

The surrounding infrastructure provides the ability to take action reliably.

Understanding the AI Agent Workflow

A typical AI agent execution flow looks like this:

                    User Request
                         |
                         v
                  Agent Harness
                         |
        +----------------+----------------+
        |                                 |
        v                                 v
 Load Always-On Context          Understand Task
        |                                 |
        |                                 v
        |                         Select Relevant Skills
        |                                 |
        |                                 v
        +------------------------ Load Skill Context
                         |
                         v
                 Retrieve Memory
                         |
                         v
              Discover Tools via MCP
                         |
                         v
                  Agent Reasoning
                         |
                         v
                  Execute Actions
                         |
                         v
              Observe Tool Results
                         |
                         v
              Update Context/Memory
                         |
                         v
                  Task Completed

At the core of this workflow is a continuous loop:

Reason → Act → Observe → Repeat

The model decides what should happen next.

The agent infrastructure makes those decisions actionable.

1. Agent Harness: The Runtime Behind the Agent

The AI Agent Harness is the execution layer that surrounds the model.

It manages:

Task execution
Context assembly
Tool access
Skill loading
Memory retrieval
Security policies
Observability

A useful analogy:

The model is the brain. The harness is the environment that allows the brain to interact with the world.

For example:

User request:

"Find customers who have not logged in for 90 days and send them a reminder email."

The model reasons:

"I need customer activity data and an email capability."

The harness handles:

Loading relevant capabilities
Accessing customer data
Generating email content
Applying approval rules
Sending the communication

The harness connects reasoning with execution.

2. Tools: Giving Agents the Ability to Act

Tools provide agents with the ability to interact with external systems.

Examples:

APIs
Databases
Search engines
Code execution environments
File systems
Business applications

Without tools, an LLM can only provide recommendations.

With tools, an agent can perform actions.

Example:

The model decides:

"I need customer information.
I will query the database."

The harness executes:

SELECT *
FROM customers
WHERE last_login < CURRENT_DATE - INTERVAL '90 days';

The result is returned to the model.

This creates the agent loop:

Reason → Tool Call → Result → Reason Again

3. Model Context Protocol (MCP): Standardizing Tool Connections

As agents become more capable, they need access to many external systems.

Managing custom integrations for every application does not scale.

This is where Model Context Protocol (MCP) becomes important.

MCP provides a standard way for AI applications to connect with external tools and data sources.

Without MCP:

Agent

 ├── Custom Database Connector
 ├── Custom File Connector
 ├── Custom API Connector
 └── Custom Search Connector

With MCP:

Agent

       |
  MCP Client

       |
 -------------------------
 |          |             |
Database   Files        APIs
MCP        MCP          MCP
Server     Server       Server

An MCP server can expose capabilities:

search_customers()

get_customer_orders()

update_customer_record()

MCP separates:

Agent reasoning
Tool implementation
Enterprise system access

4. AGENTS.md: The Agent's Always-Loaded Instructions

As agent systems grow, context management becomes critical.

Not every instruction should be loaded for every task.

AGENTS.md provides the agent with its always-available operating instructions.

It defines the baseline rules for how an agent should work.

Typical contents include:

Project conventions
Coding standards
Security rules
Repository guidelines
Environment instructions
Common workflows

Example:

project/

├── AGENTS.md
├── src/
├── tests/
└── skills/

Example AGENTS.md:

# Agent Instructions

## Project Rules

- Follow coding standards
- Run tests before committing changes
- Never expose secrets
- Update documentation when required

## Development Workflow

1. Understand the requirement
2. Inspect existing code
3. Implement changes
4. Validate results
5. Provide a summary

Because AGENTS.md is always included in the context, it should contain only essential instructions.

A large AGENTS.md increases context usage and can reduce agent effectiveness.

5. Skills: Dynamic Agent Capabilities

Skills provide specialized knowledge and workflows that are loaded only when relevant.

Unlike AGENTS.md, skills are not always included in the context.

They are selected dynamically based on the task.

Examples:

Database migration skill
Security review skill
Frontend development skill
Documentation skill

Example structure:

skills/

├── database-migration/
│   └── SKILL.md
│
├── security-review/
│   └── SKILL.md
│
└── api-development/
    └── SKILL.md

Example SKILL.md:

# Database Migration Skill

## Purpose

Safely modify database schemas.

## Workflow

1. Analyze schema changes
2. Create migration scripts
3. Validate compatibility
4. Run migration tests
5. Review rollback strategy

The harness loads this skill only when a database migration task appears.

AGENTS.md vs Skills: Why Both Matter

A common mistake is putting every instruction into AGENTS.md.

Example:

AGENTS.md

- Coding rules
- Database procedures
- Deployment workflows
- Security reviews
- Testing strategies
- Documentation rules

Over time, this file becomes too large.

The agent receives unnecessary information for every task.

A better approach:

AGENTS.md

Always loaded:
- Core rules
- Project conventions
- Security requirements


Skills

Loaded when needed:
- Database workflows
- Deployment procedures
- Security analysis
- API patterns

The goal is not maximum information.

The goal is the right information at the right time.

6. Memory: Giving Agents Continuity

LLMs are stateless by default.

Without memory, every interaction starts from zero.

Agent memory usually has multiple layers.

Short-Term Memory

Current conversation context.

Example:

User:
"My order arrived damaged."

Agent remembers:

- Order details
- Previous messages
- Current issue

Working Memory

Temporary information needed during execution.

Example:

Research Task:

Files analyzed:

- sales_report.csv
- customer_feedback.json
- product_notes.md

Long-Term Memory

Information retained across sessions.

Example:

{
  "user_preferences": {
    "communication": "email",
    "language": "English"
  }
}

Memory allows agents to become more personalized and effective.

Complete AI Agent Workflow Example

Consider a software engineering agent.

User request:

"Fix the failing payment API tests."

Step 1: Load Agent Instructions

The harness loads:

AGENTS.md

- Coding standards
- Repository rules
- Security policies

Step 2: Load Relevant Skills

The harness identifies the task and loads:

software-engineering-skill/

├── SKILL.md
├── coding-guidelines.md
└── testing-workflow.md

Step 3: Retrieve Memory

The agent recalls:

Previous changes:

- Payment API migration completed
- Database schema updated
- Authentication tests modified

Step 4: Discover Tools Through MCP

The agent accesses:

MCP Servers:

- Git repository
- CI/CD system
- Test runner
- Issue tracker

Step 5: Execute the Task

Actions:

1. Analyze failing tests
2. Inspect source code
3. Modify implementation
4. Run tests
5. Review results

Step 6: Verify and Complete

The harness validates:

Tests pass
Policies are followed
No restricted actions occurred

The agent delivers the result.

Why Agentic Workflows Matter

Building AI agents is no longer only about choosing a powerful model.

Reliable agents require:

Component	Purpose
Harness	Runs and coordinates the agent
Tools	Enable external actions
MCP	Standardizes integrations
AGENTS.md	Provides always-on instructions
Skills	Provide task-specific expertise
Memory	Maintains context over time

The model provides intelligence.

The workflow around the model provides capability.

Final Thoughts

The future of AI applications will be built around agentic workflows.

Successful AI agents will combine:

Reasoning models
Execution harnesses
Tool ecosystems
MCP-based integrations
Dynamic skills
Context-aware memory

The biggest shift is moving from:

"How do we prompt the model?"

to:

"How do we design the complete system around the model?"

That is the foundation of modern AI agent engineering.

What is an AI Agent Harness?

Naimul Karim — Wed, 22 Jul 2026 04:20:31 +0000

Large Language Models (LLMs) are incredibly good at understanding language, reasoning through problems, and generating responses. However, on their own, they cannot execute code, call APIs, access files, remember previous work, or complete multi-step workflows.

To move beyond answering prompts and actually perform tasks, an LLM needs an AI Agent Harness.

An AI Agent Harness is the software infrastructure that surrounds a Large Language Model (LLM) and enables it to interact with the outside world. It connects the model to tools, memory, execution environments, and safety controls, allowing the model's decisions to be translated into meaningful actions.

Simply put:

AI Agent = Model + Harness

Think of the model as the brain that reasons and decides what should happen next. The harness is everything around it that enables those decisions to be executed safely and reliably.

What Does an AI Agent Harness Provide?

A typical AI agent harness consists of four key capabilities.

Tools

The harness connects the model to external systems, including:

APIs
Databases
Search engines
Code execution environments
Business applications

These tools allow the agent to perform actions instead of simply generating text.

Memory

Models have limited context windows and do not remember previous interactions by default.

The harness manages:

Conversation history
User preferences
Previous workflow state
Long-term task context

This enables agents to continue work across multiple interactions.

Workspace

Agents often need an environment where they can perform tasks.

A harness provides access to:

Files
Documents
Data
Execution environments
Shared storage

This workspace allows agents to create, modify, and persist information while completing tasks.

Guardrails

Enterprise agents need to operate safely.

The harness enforces:

Permissions
Security policies
Human approval workflows
Monitoring
Governance controls

Without these safeguards, an agent could perform actions that should not happen automatically.

Why Do AI Agents Need Both a Model and a Harness?

Modern AI agents are built around two complementary layers:

Component	Responsibility
Model	Reasons, plans, and decides what to do next
Harness	Executes those decisions using tools, memory, and external systems

The model focuses on thinking.

The harness focuses on doing.

Together, they form a complete AI agent.

The Reason → Act → Observe Loop

Most AI agents operate using a continuous execution cycle known as the ReAct (Reason + Act) pattern.

Reason
   |
   v
Act
   |
   v
Observe
   |
   v
Repeat

1. Reason

The model analyzes:

The user's request
Available context
Previous results

It determines the next action required to move toward the goal.

2. Act

The harness executes that action by:

Calling an API
Running code
Querying a database
Searching external sources
Updating files

3. Observe

The result of that action is returned to the model as new context.

4. Repeat

The model reasons again using the updated information.

This cycle continues until the task is completed.

For example, consider a coding agent fixing a bug:

The model proposes a code change.
The harness runs the code in an isolated sandbox.
Test results are returned to the model.
If tests fail, the model analyzes the errors and tries another approach.

The model focuses on solving the problem, while the harness manages execution and feedback.

Model vs Harness vs Agent

These terms are often used interchangeably, but they represent different parts of an AI system.

Component	What it Does	Analogy
Model	Reasons and generates outputs	Brain
Harness	Executes actions, manages memory, tools, and policies	Body and workspace
Agent	Complete system combining model and harness	Worker that can think and act

The agent is not just the model.

It is the combination of intelligent reasoning and the infrastructure required to turn decisions into real-world actions.

Core Building Blocks of an AI Agent Harness

Most production-ready harnesses include several foundational components.

System Prompts

System prompts provide persistent instructions that define:

The agent's role
Objectives
Rules
Behavioral constraints

They establish the operating guidelines before the agent begins a task.

Tool Execution

The model decides which tool should be used.

The harness is responsible for:

Executing the tool
Handling authentication
Capturing results
Returning information back to the model

Execution Environments (Sandboxes)

Running AI-generated code directly on production systems creates security risks.

Sandboxes provide isolated environments where agents can:

Execute code safely
Experiment
Run tests
Avoid unintended system changes

Filesystem and Storage

Long-running tasks require persistent storage.

The harness manages:

Files
Intermediate results
Notes
Plans
Generated artifacts

This allows agents to maintain progress across sessions.

Memory and Context Management

Models have limited context windows, so the harness manages what information remains available.

This includes:

Keeping relevant information active
Summarizing older conversations
Retrieving previous task history

Good context management helps agents maintain performance during complex workflows.

Feedback and Self-Verification

Reliable agents do not simply generate output and stop.

The harness can:

Run tests
Validate results
Check outputs
Ask the model to review its own work

These feedback loops allow agents to detect mistakes and improve their actions.

Guardrails and Human-in-the-Loop Controls

Some actions require human approval.

Examples include:

Sending external communications
Making financial transactions
Deleting important data

The harness can introduce approval checkpoints before executing sensitive operations.

Observability and Logging

Production systems need visibility into agent behavior.

The harness records:

Tool calls
Execution traces
Latency
Errors
Token usage
Workflow history

This helps developers debug, evaluate, and improve agent systems.

Why Harness Design Matters

As LLMs become more capable, the harness becomes an increasingly important factor in agent performance.

A strong harness improves:

Context management
Tool orchestration
Memory handling
Verification
Safety
Reliability

In many real-world scenarios, a well-designed harness around a smaller model can outperform a more capable model with poor execution infrastructure.

The future of AI performance will depend not only on better models but also on better systems built around those models.

Harness Engineering: The Next Evolution

AI development has evolved through several stages:

Discipline	Focus
Prompt Engineering	Writing better instructions for models
Context Engineering	Controlling the information provided to models
Harness Engineering	Designing the complete runtime environment around models

Prompt engineering and context engineering are now becoming parts of a broader discipline: Harness Engineering.

Harness engineering focuses on building the complete ecosystem that allows AI agents to operate reliably in real-world environments.

Final Thoughts

A language model provides intelligence, but intelligence alone does not create an AI agent.

An AI Agent Harness transforms that intelligence into action by connecting the model to tools, memory, execution environments, and safety mechanisms.

As AI agents become more autonomous and move into production systems, harnesses will become one of the most important layers of the AI technology stack.

The future of AI will not be defined only by the models we build. It will also be defined by the quality of the harnesses that allow those models to work effectively.

How I Fixed Windows 11 Sleep Not Working by Tracking Down a Hidden WebView2 Video Wake Lock

Naimul Karim — Wed, 22 Jul 2026 02:59:39 +0000

Have you ever configured your Windows laptop to sleep after a few minutes of inactivity, only to find the screen never turns off?

I recently ran into this issue on my Dell Inspiron 16 running Windows 11 Pro, and after hours of troubleshooting, I discovered the culprit wasn't Windows itself—it was an application using Microsoft Edge WebView2.

Here's how I diagnosed and fixed it.

🖥️ The Problem

My power settings were configured correctly:

Display turns off after 3 minutes
Sleep after 3 minutes
Hibernate enabled

Despite that, the laptop would remain awake indefinitely. The display never turned off, and the system never entered sleep.

🔍 Step 1: Check for Power Requests

Windows includes a built-in command that tells you what's preventing your computer from sleeping.

Open Command Prompt as Administrator and run:

powercfg /requests

The output looked something like this:

DISPLAY:
[PROCESS] msedgewebview2.exe
Video Wake Lock

The important part was Video Wake Lock.

A Video Wake Lock tells Windows that media playback is active, so Windows intentionally keeps the display awake.

🔎 Step 2: Find Which Application Owns WebView2

Many Windows applications use Microsoft Edge WebView2, so simply seeing msedgewebview2.exe doesn't tell you which application is responsible.

I used PowerShell to identify the parent process for each WebView2 instance:

Get-CimInstance Win32_Process |
Where-Object {$_.Name -eq "msedgewebview2.exe"} |
Select-Object ProcessId, ParentProcessId,
@{
    Name="Host"
    Expression={
        (Get-CimInstance Win32_Process -Filter "ProcessId=$($_.ParentProcessId)").Name
    }
} | Sort-Object Host

The output revealed several applications using WebView2:

Widgets.exe
Microsoft Teams
SearchHost.exe
Visual Studio (devenv.exe)
PCAppStore.exe

At this point I still didn't know which one was preventing sleep.

🧪 Step 3: Eliminate Processes One by One

I terminated each host process individually and checked the power requests again.

Stop-Process -Id <PID> -Force

After each process was stopped, I reran:

powercfg /requests

When I terminated PCAppStore.exe, the output immediately changed to:

DISPLAY:
None.

🎉 That was the smoking gun.

PCAppStore.exe was holding a Video Wake Lock through WebView2, preventing Windows from turning off the display or entering sleep.

💻 Step 4: Verify Sleep Support

To ensure there wasn't a hardware limitation, I checked the supported sleep states:

powercfg /a

The output showed:

Standby (S0 Low Power Idle)
Hibernate

This means the laptop uses Modern Standby (S0) rather than the traditional S3 Sleep.

Modern Standby is more sensitive to applications requesting wake locks, making powercfg /requests an essential troubleshooting tool.

✅ Step 5: Fix the Root Cause

Once I identified the offending application, the fix was straightforward:

Disable the application from Startup
Close it when not needed
Uninstall it if you never use it

After preventing PCAppStore from running, my laptop finally behaved as expected:

✅ Display turns off after 3 minutes
✅ Laptop enters sleep automatically
✅ Wake-up works normally

🔐 Bonus: Require a PIN After Sleep

After fixing sleep, I noticed another issue:

The laptop woke directly to the desktop instead of asking for my PIN.

To fix that:

Settings → Accounts → Sign-in options

Configure:

If you've been away, when should Windows require you to sign in again?

Choose the shortest available delay (or Immediately, depending on your Windows version).

🛠 Useful Commands

Check what's preventing sleep

powercfg /requests

View supported sleep states

powercfg /a

Generate an energy report

powercfg /energy

Generate a Sleep Study report

powercfg /sleepstudy

Show devices allowed to wake the PC

powercfg /devicequery wake_armed

💡 Lessons Learned

A few things I learned from this experience:

Start with powercfg /requests whenever Windows won't sleep.
msedgewebview2.exe is often just the messenger—you need to identify the parent application.
Modern Standby systems are more susceptible to applications holding wake locks.
Third-party utilities can unintentionally interfere with Windows power management.

Final Thoughts

Initially, I suspected Windows, Dell firmware, or Modern Standby itself.

In reality, a background application was keeping the display awake by holding a WebView2 Video Wake Lock.

If your Windows laptop refuses to sleep despite correct power settings, don't overlook background applications.

A single process may be the only thing standing between you and a properly sleeping system.

Hopefully this saves someone else a few hours of troubleshooting.

Have you encountered a similar issue?

I'd love to hear what prevented sleep on your machine.

Share your experience in the comments!

Windows #Windows11 #PowerManagement #Troubleshooting #WebView2 #PowerShell #Dell #ModernStandby #DeveloperTips

Building a Secure Real-Time Messaging App with .NET 8 and Angular 18

Naimul Karim — Fri, 22 May 2026 04:42:50 +0000

A deep dive into JWT authentication, AES-256-GCM encryption, SignalR, and production security patterns.

Introduction

Real-time messaging apps are everywhere, but most tutorials gloss over the hard parts — the security. In this post I'll walk you through SecureChat, a production-grade messaging app I built with .NET 8 and Angular 18. By the end you'll understand:

How to encrypt messages at rest using AES-256-GCM
How to build a JWT + rotating refresh token authentication flow
How to wire up SignalR with a Redis backplane for real-time delivery
How to implement a silent token refresh interceptor in Angular
How to layer in rate limiting, security headers, and an audit trail

The full source is on GitHub: github.com/naimulkarim/SecureChat

Architecture Overview

Before we dive into code, here's the full picture:

┌─────────────────────────────────────────────┐
│             Angular 18 Frontend             │
│   Auth guard · Chat module · JWT interceptor│
└──────────────────┬──────────────────────────┘
                   │ HTTPS + WSS (TLS 1.3)
┌──────────────────▼──────────────────────────┐
│              .NET 8 Web API                 │
│  Auth API · Messages API · SignalR Hub      │
│  Rate limiting · JWT · Security headers     │
└────┬──────────────────┬───────────────┬─────┘
     │                  │               │
┌────▼────┐     ┌───────▼──────┐  ┌────▼─────┐
│SQL Server│     │    Redis     │  │  Azure   │
│Users/Msgs│     │Cache/Backpl. │  │  Blobs   │
└──────────┘     └──────────────┘  └──────────┘

The key design decisions:

Short-lived JWTs (15 min) limit the blast radius if a token is stolen
Rotating refresh tokens mean a stolen refresh token can only be used once
AES-256-GCM encrypts every message before it hits the database
Redis backplane allows the SignalR hub to scale across multiple API instances
Per-user SignalR groups deliver messages to all of a user's devices simultaneously

Part 1 — The .NET 8 Backend

Setting up `Program.cs`

The entry point wires together every security concern. Let me break it down section by section.

JWT Authentication

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(jwtKey)),
            ValidateIssuer   = true,
            ValidIssuer      = builder.Configuration["Jwt:Issuer"],
            ValidateAudience = true,
            ValidAudience    = builder.Configuration["Jwt:Audience"],
            ValidateLifetime = true,
            ClockSkew        = TimeSpan.Zero   // ← no grace period on expiry
        };

        // SignalR WebSocket upgrades can't send headers,
        // so we read the token from the query string instead
        options.Events = new JwtBearerEvents
        {
            OnMessageReceived = ctx =>
            {
                var token = ctx.Request.Query["access_token"];
                if (!string.IsNullOrEmpty(token) &&
                    ctx.HttpContext.Request.Path.StartsWithSegments("/hubs"))
                    ctx.Token = token;
                return Task.CompletedTask;
            }
        };
    });

The ClockSkew = TimeSpan.Zero is intentional. The default is 5 minutes, meaning a "15-minute" token actually lives for 20 minutes. That's an unnecessary exposure window.

The OnMessageReceived event is needed because WebSocket upgrade requests can't carry Authorization headers — the browser spec doesn't allow it. So the Angular client appends the JWT as a query parameter only for hub connections.

Rate Limiting

builder.Services.AddRateLimiter(opt =>
{
    opt.AddFixedWindowLimiter("message", lim =>
    {
        lim.Window      = TimeSpan.FromMinutes(1);
        lim.PermitLimit = 60;
    });
    opt.AddFixedWindowLimiter("auth", lim =>
    {
        lim.Window      = TimeSpan.FromMinutes(5);
        lim.PermitLimit = 10;   // max 10 login attempts per 5 min
    });
});

Auth endpoints get a stricter limit to slow down brute-force attacks. Message endpoints are generous enough for normal usage but will stop a script flooding the server.

Security Headers

app.Use(async (ctx, next) =>
{
    ctx.Response.Headers.Append("X-Content-Type-Options", "nosniff");
    ctx.Response.Headers.Append("X-Frame-Options",        "DENY");
    ctx.Response.Headers.Append("X-XSS-Protection",       "1; mode=block");
    ctx.Response.Headers.Append("Referrer-Policy",         "no-referrer");
    ctx.Response.Headers.Append("Content-Security-Policy",
        "default-src 'self'; connect-src 'self' wss:");
    await next();
});

These headers are cheap to add and block an entire category of attacks — MIME sniffing, clickjacking, and cross-site scripting.

Authentication Service — JWT + BCrypt + Refresh Tokens

The AuthService handles the full auth lifecycle.

Registration

public async Task<AuthResult> RegisterAsync(RegisterRequest req)
{
    if (await _db.Users.AnyAsync(u => u.Email == req.Email.ToLower()))
        return AuthResult.Fail("Email already registered.");

    var user = new User
    {
        Id           = Guid.NewGuid().ToString(),
        Email        = req.Email.ToLower().Trim(),
        DisplayName  = req.DisplayName.Trim(),
        PasswordHash = BCrypt.Net.BCrypt.HashPassword(req.Password, workFactor: 12),
        CreatedAt    = DateTime.UtcNow,
    };

    _db.Users.Add(user);
    await _db.SaveChangesAsync();
    await _audit.LogAsync("auth.register", user.Id, null);

    return await IssueTokensAsync(user);
}

Work factor 12 for BCrypt means ~250ms to hash a password on modern hardware — fast enough for users, slow enough to make brute-forcing impractical.

JWT Generation

private string GenerateJwt(User user)
{
    var key   = new SymmetricSecurityKey(
        Encoding.UTF8.GetBytes(_config["Jwt:Key"]!));
    var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

    var claims = new[]
    {
        new Claim(ClaimTypes.NameIdentifier, user.Id),
        new Claim(ClaimTypes.Email,          user.Email),
        new Claim(ClaimTypes.Name,           user.DisplayName),
        new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
    };

    var token = new JwtSecurityToken(
        issuer:             _config["Jwt:Issuer"],
        audience:           _config["Jwt:Audience"],
        claims:             claims,
        expires:            DateTime.UtcNow.AddMinutes(15),
        signingCredentials: creds);

    return new JwtSecurityTokenHandler().WriteToken(token);
}

The Jti (JWT ID) claim is a unique identifier for each token. This is what lets you build a token blocklist if you ever need to revoke individual tokens before expiry.

Rotating Refresh Tokens

public async Task<AuthResult> RefreshAsync(string refreshToken)
{
    var stored = await _db.RefreshTokens
        .Include(r => r.User)
        .FirstOrDefaultAsync(r => r.Token == refreshToken && !r.IsRevoked);

    if (stored is null || stored.ExpiresAt < DateTime.UtcNow)
        return AuthResult.Fail("Invalid or expired refresh token.");

    stored.IsRevoked = true;   // ← revoke old token immediately
    await _db.SaveChangesAsync();

    return await IssueTokensAsync(stored.User);   // ← issue fresh pair
}

Rotation means every successful refresh invalidates the old token and issues a new one. If an attacker steals a refresh token and uses it, the legitimate user's next refresh will detect the conflict (token already revoked) and you can force a full re-login.

Encryption Service — AES-256-GCM

This is the most security-critical piece of the backend.

public string Encrypt(string plaintext)
{
    // Fresh 96-bit nonce for every single message
    var nonce = new byte[AesGcm.NonceByteSizes.MaxSize];
    RandomNumberGenerator.Fill(nonce);

    var plaintextBytes = Encoding.UTF8.GetBytes(plaintext);
    var ciphertext     = new byte[plaintextBytes.Length];
    var tag            = new byte[AesGcm.TagByteSizes.MaxSize]; // 128-bit auth tag

    using var aes = new AesGcm(_key, tag.Length);
    aes.Encrypt(nonce, plaintextBytes, ciphertext, tag);

    // Pack: [nonce 12B][tag 16B][ciphertext nB]
    var combined = new byte[nonce.Length + tag.Length + ciphertext.Length];
    Buffer.BlockCopy(nonce,      0, combined, 0,                        nonce.Length);
    Buffer.BlockCopy(tag,        0, combined, nonce.Length,              tag.Length);
    Buffer.BlockCopy(ciphertext, 0, combined, nonce.Length + tag.Length, ciphertext.Length);

    return Convert.ToBase64String(combined);
}

Why AES-256-GCM specifically?

AES-256 — the key length (256 bits) is computationally infeasible to brute-force
GCM mode — provides both confidentiality (encryption) and integrity (the 128-bit authentication tag). If anyone tampers with the ciphertext in the database, decryption throws an exception rather than silently returning garbage
Fresh nonce per message — reusing a nonce with the same key in GCM mode catastrophically breaks security. We use RandomNumberGenerator.Fill (cryptographically secure) for each encryption call

The nonce and tag are packed together with the ciphertext so decryption is self-contained — no separate columns needed.

SignalR Hub

[Authorize]
public class ChatHub : Hub
{
    public override async Task OnConnectedAsync()
    {
        var userId = GetUserId();
        // Each user gets a personal group across all their devices
        await Groups.AddToGroupAsync(Context.ConnectionId, $"user:{userId}");
        await _audit.LogAsync("hub.connected", userId,
            Context.GetHttpContext()?.Connection.RemoteIpAddress?.ToString());
        await base.OnConnectedAsync();
    }

    public async Task SendMessage(SendMessageRequest request)
    {
        if (string.IsNullOrWhiteSpace(request.Content) || request.Content.Length > 4000)
            throw new HubException("Invalid message content.");

        var senderId = GetUserId();
        var saved    = await _messages.SaveAsync(senderId, request);

        // Fan out to every participant's group (covers multi-device)
        foreach (var participantId in saved.ParticipantIds)
        {
            await Clients.Group($"user:{participantId}")
                .SendAsync("ReceiveMessage", saved);
        }
    }

    public async Task SendTyping(string conversationId, bool isTyping)
    {
        var userId       = GetUserId();
        var participants = await _messages.GetParticipantsAsync(conversationId, userId);

        foreach (var participantId in participants.Where(p => p != userId))
        {
            await Clients.Group($"user:{participantId}")
                .SendAsync("TypingIndicator",
                    new { conversationId, userId, isTyping });
        }
    }
}

A few design decisions worth noting:

Personal groups vs connection IDs. We add each connection to user:{userId} instead of tracking individual ConnectionId values. This means if a user has two browser tabs open, both get the message without any extra code. If you used ConnectionId you'd need a lookup table mapping users to connections.

Typing indicators are never persisted. They're pure ephemeral SignalR events — no database write, no message history. They disappear the moment the connection drops.

HubException for client-visible errors. Regular C# exceptions become generic 500-style errors on the client. HubException propagates the message string to the caller, which lets Angular show a human-readable error.

Part 2 — The Angular 18 Frontend

JWT Interceptor with Silent Refresh

This is the piece most tutorials get wrong. The naive approach — refresh on 401, retry — breaks badly when multiple requests expire simultaneously. Our interceptor queues concurrent requests while a refresh is in flight.

let isRefreshing = false;
const refreshSubject = new BehaviorSubject<string | null>(null);

export const authInterceptor: HttpInterceptorFn = (req, next) => {
  const auth  = inject(AuthService);
  const token = auth.accessToken();

  const addToken = (r: typeof req, t: string) =>
    r.clone({ setHeaders: { Authorization: `Bearer ${t}` } });

  const request = token ? addToken(req, token) : req;

  return next(request).pipe(
    catchError((err: HttpErrorResponse) => {
      if (err.status !== 401 || req.url.includes('/auth/'))
        return throwError(() => err);

      if (isRefreshing) {
        // Another request is already refreshing — wait for it
        return refreshSubject.pipe(
          filter((t): t is string => t !== null),
          take(1),
          switchMap(t => next(addToken(req, t)))
        );
      }

      isRefreshing = true;
      refreshSubject.next(null);   // signal "refreshing in progress"

      return auth.refresh$().pipe(
        switchMap(newToken => {
          isRefreshing = false;
          refreshSubject.next(newToken);   // unblock queued requests
          return next(addToken(req, newToken));
        }),
        catchError(refreshErr => {
          isRefreshing = false;
          auth.logout();
          return throwError(() => refreshErr);
        })
      );
    })
  );
};

Walk through the flow:

Request goes out with the current JWT
Server returns 401 (token expired)
If no refresh is in progress, start one and set isRefreshing = true
All other requests that 401 in the meantime subscribe to refreshSubject and wait
When refresh succeeds, refreshSubject.next(newToken) unblocks all queued requests
Each queued request clones itself with the new token and retries

Without this queuing, three simultaneous expired requests would trigger three parallel refresh calls, the second and third would fail (token already rotated), and the user would be logged out unexpectedly.

SignalR Chat Service with Angular Signals

@Injectable({ providedIn: 'root' })
export class ChatService {
  // Reactive state using Angular 18 signals
  messages      = signal<Message[]>([]);
  conversations = signal<Conversation[]>([]);
  typingUsers   = signal<TypingIndicator[]>([]);
  connected     = signal(false);

  // Derived state — no manual subscription management
  unreadCount = computed(() =>
    this.conversations().reduce((sum, c) => sum + c.unreadCount, 0)
  );

  async connect(): Promise<void> {
    this.hub = new signalR.HubConnectionBuilder()
      .withUrl(`${environment.apiUrl}/hubs/chat`, {
        accessTokenFactory: () => this.auth.accessToken() ?? '',
        transport: signalR.HttpTransportType.WebSockets,
        skipNegotiation: true,
      })
      .withAutomaticReconnect([0, 2000, 5000, 10000, 30000])
      .build();

    this.hub.on('ReceiveMessage', (msg: Message) => {
      this.messages.update(msgs => [...msgs, msg]);
      this.conversations.update(convs =>
        convs.map(c =>
          c.id === msg.conversationId
            ? { ...c, lastMessage: msg, unreadCount: c.unreadCount + 1 }
            : c
        )
      );
    });

    // ...
    await this.hub.start();
    this.connected.set(true);
  }
}

accessTokenFactory is a function, not a value. SignalR calls it on every reconnect attempt, so it will always pick up the freshest token (including any that were silently refreshed by the interceptor).

withAutomaticReconnect([0, 2000, 5000, 10000, 30000]) defines a custom backoff schedule — immediate retry, then 2s, 5s, 10s, 30s. After exhausting this list SignalR stops retrying, which lets you show a "connection lost" UI rather than hammering the server forever.

Using Angular signals instead of RxJS BehaviorSubject keeps the state management simple — components read chatService.messages() directly in their templates and Angular handles change detection automatically.

Part 3 — Security Checklist

Here's every security mechanism in the app and why it's there:

Threat	Mitigation
Password database breach	BCrypt, work factor 12
Token theft	JWT expiry 15 min, `ClockSkew = Zero`
Refresh token theft	Server-side rotation — stolen token is single-use
Eavesdropping in transit	HTTPS + WSS enforced, TLS 1.3
Database breach (messages)	AES-256-GCM at rest
GCM nonce reuse	`RandomNumberGenerator.Fill` per message
Message tampering	GCM authentication tag — tampered ciphertext throws
Brute-force login	Rate limit: 10 attempts / 5 min
Message flooding	Rate limit: 60 messages / min
Clickjacking	`X-Frame-Options: DENY`
MIME sniffing	`X-Content-Type-Options: nosniff`
Unauthorized hub access	`[Authorize]` attribute, JWT validated on upgrade
Hub conversation access	Server-side participant check before join/deliver
XSS	`Content-Security-Policy: default-src 'self'`
Forensics / incident response	Append-only audit log on every auth event

Part 4 — Running It Locally

# Clone
git clone https://github.com/naimulkarim/SecureChat.git
cd SecureChat

# Generate secrets
openssl rand -base64 32   # → Encryption:Key
openssl rand -base64 64   # → Jwt:Key

# Backend
cd SecureChat.API
# Add secrets to appsettings.Development.json (never commit this file)
dotnet ef database update
dotnet run

# Frontend (new terminal)
cd ../secure-chat-ui
npm install
ng serve

Navigate to https://localhost:4200.

What's Next

There are a few things I'd add before calling this truly production-ready:

Key management — move the AES key and JWT secret out of appsettings.json and into Azure Key Vault (or AWS Secrets Manager). The current setup is fine for local dev but secrets should never live in a config file in a real deployment.

Client-side encryption — the current model encrypts at the server before writing to the DB. True end-to-end encryption (where even the server can't read messages) requires encrypting on the client with the recipient's public key. This would involve WebCrypto API on the Angular side and a public key exchange flow.

Message deletion / expiry — a GDPR-friendly implementation needs the ability to delete or expire messages, with the encrypted blobs actually removed from storage.

Push notifications — when the user isn't connected to the hub, they need push notifications. Web Push API + a service worker can deliver notifications even when the tab is closed.

Conclusion

The patterns in this post — short-lived JWTs with rotating refresh tokens, AES-GCM encryption at rest, request queuing during token refresh, and per-user SignalR groups — are the foundations of any serious real-time app. None of them are particularly exotic, but getting all the details right (nonce freshness, clock skew, refresh token rotation, concurrent refresh queuing) makes the difference between a demo and something you'd trust with real user data.

The full source is at github.com/naimulkarim/SecureChat. PRs and issues welcome.

Tags: dotnet angular security signalr webdev csharp typescript

🔐 SecretVault Internals: How the Code Is Actually Implemented

Naimul Karim — Tue, 19 May 2026 02:46:31 +0000

This is the implementation companion to the SecretVault introduction post. Where that post showed you what SecretVault does, this one shows you how it's built — every class, every design decision, and why things are structured the way they are.

Project Structure at a Glance

SecretVault/
├── src/
│   ├── SecretVault.Core/                  # Abstractions, caching, chaining
│   │   ├── ISecretManager.cs
│   │   ├── ISecretRotationManager.cs
│   │   ├── Models.cs
│   │   ├── CachedSecretManager.cs
│   │   └── ChainedSecretManager.cs
│   ├── SecretVault.Aws/                   # AWS Secrets Manager
│   │   └── AwsSecretManager.cs
│   ├── SecretVault.Azure/                 # Azure Key Vault
│   │   └── AzureKeyVaultSecretManager.cs
│   ├── SecretVault.HashiCorp/             # HashiCorp Vault KV v2
│   │   └── HashiCorpVaultSecretManager.cs
│   ├── SecretVault.Gcp/                   # GCP Secret Manager
│   │   └── GcpSecretManager.cs
│   └── SecretVault.Extensions.Hosting/   # ASP.NET Core integration
│       ├── SecretVaultServiceExtensions.cs
│       └── SecretVaultHealthCheck.cs
└── tests/
    └── SecretVault.Core.Tests/
        └── CachedAndChainedTests.cs

The golden rule: if a class only references ISecretManager → it goes in Core. If it references a provider SDK (AWS, Azure, etc.) → it goes in that provider's project.

Part 1 — The Core Abstractions

`ISecretManager` — The Unified Interface

This is the only type your application code ever depends on:

namespace SecretVault.Core;

public interface ISecretManager
{
    // On-demand runtime fetching
    Task<string?> GetSecretAsync(string secretName, CancellationToken ct = default);
    Task<T?> GetSecretAsync<T>(string secretName, CancellationToken ct = default);
    Task SetSecretAsync(string secretName, string value, CancellationToken ct = default);
    Task DeleteSecretAsync(string secretName, CancellationToken ct = default);

    // Bulk fetch — useful at startup to warm secrets
    Task<IReadOnlyDictionary<string, string?>> GetSecretsAsync(
        IEnumerable<string> secretNames, CancellationToken ct = default);
}

Why string? and not string? Returning null instead of throwing when a secret doesn't exist is a deliberate choice — it lets callers decide whether a missing secret is an error or an expected condition without forcing a try/catch everywhere.

Why Task<T?> GetSecretAsync<T>? Many secrets are stored as JSON objects (e.g. a database config with host, port, and password together). The generic overload deserializes directly into your type so you don't have to JsonSerializer.Deserialize manually on every call.

`ISecretRotationManager` — Rotation on Top

Rotation is an optional capability — not every use case needs it. So instead of bloating ISecretManager, we extend it:

public interface ISecretRotationManager : ISecretManager
{
    Task<SecretRotationResult> RotateSecretAsync(
        string secretName,
        string newValue,
        TimeSpan? gracePeriod = null,
        CancellationToken ct = default);

    Task<IReadOnlyList<SecretVersion>> ListVersionsAsync(
        string secretName, CancellationToken ct = default);

    Task<string?> GetSecretVersionAsync(
        string secretName, string version, CancellationToken ct = default);
}

All four provider implementations (AwsSecretManager, AzureKeyVaultSecretManager, etc.) implement ISecretRotationManager — which means they also satisfy ISecretManager. You can inject either interface depending on what you need.

The return types:

// Returned from RotateSecretAsync — tells you what happened
public record SecretRotationResult(
    string SecretName,
    string NewVersion,
    string? PreviousVersion,
    DateTimeOffset RotatedAt,
    DateTimeOffset? GracePeriodEndsAt  // null if no grace period requested
);

// One entry from ListVersionsAsync
public record SecretVersion(
    string Version,
    DateTimeOffset CreatedAt,
    bool IsCurrent,
    string? Status
);

C# records are used here because these are pure data carriers — immutable, with built-in equality and ToString(). No behaviour, no setters.

The Exception Hierarchy

Provider SDKs throw completely different exceptions — AmazonServiceException, RequestFailedException, RpcException. Your application shouldn't need to know which one it got. We normalize them:

// Base — all SecretVault errors derive from this
public class SecretVaultException : Exception { ... }

// Secret doesn't exist in the provider
public class SecretNotFoundException : SecretVaultException
{
    public string SecretName { get; }  // carry the name so callers can log it
}

// IAM / RBAC permissions failure
public class SecretAccessDeniedException : SecretVaultException { ... }

// Network outage or provider down
public class SecretProviderUnavailableException : SecretVaultException { ... }

Each provider catches its own SDK exception types and re-throws as the appropriate SecretVaultException. Your application catches one hierarchy regardless of which provider is running:

catch (SecretNotFoundException ex)    { /* missing secret */ }
catch (SecretAccessDeniedException)   { /* permissions issue */ }
catch (SecretProviderUnavailableException) { /* outage */ }

Part 2 — The AWS Implementation

AwsSecretManager implements ISecretRotationManager (which includes all of ISecretManager):

public class AwsSecretManager : ISecretRotationManager
{
    private readonly IAmazonSecretsManager _client;
    private readonly ILogger<AwsSecretManager> _logger;

    public AwsSecretManager(IAmazonSecretsManager client, ILogger<AwsSecretManager> logger)
    {
        _client = client;
        _logger = logger;
    }

IAmazonSecretsManager not AmazonSecretsManagerClient — we take the interface, not the concrete class. This makes the provider testable via mocking without hitting real AWS.

GetSecretAsync

public async Task<string?> GetSecretAsync(string secretName, CancellationToken ct = default)
{
    try
    {
        _logger.LogDebug("Fetching secret '{Name}' from AWS Secrets Manager", secretName);

        var response = await _client.GetSecretValueAsync(new GetSecretValueRequest
        {
            SecretId = secretName
        }, ct);

        // AWS can return either a string OR binary — handle both
        return response.SecretString
            ?? Convert.ToBase64String(response.SecretBinary.ToArray());
    }
    catch (ResourceNotFoundException)
    {
        throw new SecretNotFoundException(secretName);   // normalize
    }
    catch (AmazonServiceException ex) when (ex.ErrorCode == "AccessDeniedException")
    {
        throw new SecretAccessDeniedException(secretName, ex);  // normalize
    }
    catch (Exception ex)
    {
        throw new SecretProviderUnavailableException("AWS Secrets Manager", ex); // normalize
    }
}

Exception filters (when) are used to catch only the specific AWS error codes we care about, letting other AmazonServiceException subtypes fall through to the general handler.

SetSecretAsync — Create or Update

public async Task SetSecretAsync(string secretName, string value, CancellationToken ct = default)
{
    try
    {
        await _client.PutSecretValueAsync(new PutSecretValueRequest
        {
            SecretId = secretName,
            SecretString = value
        }, ct);
    }
    catch (ResourceNotFoundException)
    {
        // Secret doesn't exist yet — create it first
        await _client.CreateSecretAsync(new CreateSecretRequest
        {
            Name = secretName,
            SecretString = value
        }, ct);
    }
}

AWS PutSecretValue requires the secret to already exist. We catch ResourceNotFoundException and create it automatically so callers don't have to think about whether a secret is new or existing.

RotateSecretAsync

public async Task<SecretRotationResult> RotateSecretAsync(
    string secretName, string newValue, TimeSpan? gracePeriod = null, CancellationToken ct = default)
{
    // 1. Read the current version ID before rotating
    var current = await _client.DescribeSecretAsync(
        new DescribeSecretRequest { SecretId = secretName }, ct);
    var previousVersion = current.VersionIdsToStages?.Keys.FirstOrDefault();

    // 2. Write the new value, explicitly marking it as current
    await _client.PutSecretValueAsync(new PutSecretValueRequest
    {
        SecretId = secretName,
        SecretString = newValue,
        VersionStages = ["AWSCURRENT"]
    }, ct);

    // 3. Read back the new version ID
    var describe = await _client.DescribeSecretAsync(
        new DescribeSecretRequest { SecretId = secretName }, ct);
    var newVersion = describe.VersionIdsToStages?.Keys.FirstOrDefault() ?? "unknown";

    var rotatedAt = DateTimeOffset.UtcNow;

    return new SecretRotationResult(
        SecretName: secretName,
        NewVersion: newVersion,
        PreviousVersion: previousVersion,
        RotatedAt: rotatedAt,
        GracePeriodEndsAt: gracePeriod.HasValue ? rotatedAt.Add(gracePeriod.Value) : null
    );
}

The AWSCURRENT stage label is how AWS tracks which version is active. The old version automatically moves to AWSPREVIOUS — staying accessible during the grace period before it expires.

Part 3 — CachedSecretManager (The Decorator Pattern)

CachedSecretManager is a decorator — it wraps any ISecretManager and adds caching without modifying the wrapped class:

Your App → CachedSecretManager → AwsSecretManager → AWS API

public class CachedSecretManager : ISecretManager
{
    private readonly ISecretManager _inner;   // the real provider
    private readonly IMemoryCache _cache;
    private readonly ILogger<CachedSecretManager> _logger;
    private readonly CachedSecretManagerOptions _options;

    public CachedSecretManager(
        ISecretManager inner,
        IMemoryCache cache,
        ILogger<CachedSecretManager> logger,
        CachedSecretManagerOptions? options = null)
    {
        _inner = inner;
        _cache = cache;
        _logger = logger;
        _options = options ?? new CachedSecretManagerOptions(); // defaults to 5 min
    }

GetSecretAsync — Cache-Aside Pattern

public async Task<string?> GetSecretAsync(string secretName, CancellationToken ct = default)
{
    var cacheKey = CacheKey(secretName);  // "secretvault:my-secret"

    // 1. Check cache first
    if (_cache.TryGetValue(cacheKey, out string? cached))
    {
        _logger.LogDebug("Cache hit for secret '{SecretName}'", secretName);
        return cached;
    }

    // 2. Cache miss — fetch from the real provider
    _logger.LogDebug("Cache miss for '{SecretName}', fetching from provider", secretName);
    var value = await _inner.GetSecretAsync(secretName, ct);

    // 3. Store in cache (only if we got a value)
    if (value is not null)
    {
        _cache.Set(cacheKey, value, new MemoryCacheEntryOptions
        {
            AbsoluteExpirationRelativeToNow = _options.AbsoluteExpiration,
            SlidingExpiration = _options.SlidingExpiration
        });
    }

    return value;
}

This is the classic cache-aside (lazy loading) pattern: populate the cache on demand, not upfront.

Write-Through Cache Invalidation

public async Task SetSecretAsync(string secretName, string value, CancellationToken ct = default)
{
    await _inner.SetSecretAsync(secretName, value, ct);  // write to provider first
    _cache.Remove(CacheKey(secretName));                 // then invalidate cache
}

Why invalidate instead of update? Updating the cache after a write seems logical but introduces a race condition — between the write and the cache update, another thread could read the old value. Invalidating forces the next read to fetch fresh from the provider, which is always safe.

Bulk Fetch — Partial Cache Hits

public async Task<IReadOnlyDictionary<string, string?>> GetSecretsAsync(
    IEnumerable<string> secretNames, CancellationToken ct = default)
{
    var result = new Dictionary<string, string?>();
    var missing = new List<string>();   // secrets not in cache

    // 1. Check cache for each name
    foreach (var name in secretNames)
    {
        if (_cache.TryGetValue(CacheKey(name), out string? cached))
            result[name] = cached;     // cache hit
        else
            missing.Add(name);         // needs fetching
    }

    // 2. Fetch only the ones that weren't cached
    if (missing.Count > 0)
    {
        var fetched = await _inner.GetSecretsAsync(missing, ct);
        foreach (var (key, value) in fetched)
        {
            result[key] = value;
            if (value is not null)
                _cache.Set(CacheKey(key), value, _options.AbsoluteExpiration);
        }
    }

    return result;
}

If you request 10 secrets and 7 are cached, only 3 API calls go to the provider. The result dictionary combines both.

The Options Class

public class CachedSecretManagerOptions
{
    // Expires exactly N minutes after caching, regardless of usage
    public TimeSpan AbsoluteExpiration { get; set; } = TimeSpan.FromMinutes(5);

    // Resets the timer on every access — null means disabled
    public TimeSpan? SlidingExpiration { get; set; }
}

You can combine both: sliding keeps frequently-accessed secrets warm, while absolute prevents them from living in cache indefinitely even if constantly hit.

Part 4 — ChainedSecretManager (The Chain of Responsibility Pattern)

public class ChainedSecretManager : ISecretManager
{
    private readonly IReadOnlyList<ISecretManager> _managers;

    public ChainedSecretManager(
        IEnumerable<ISecretManager> managers,
        ILogger<ChainedSecretManager> logger)
    {
        _managers = managers.ToList();
        if (_managers.Count == 0)
            throw new ArgumentException("At least one ISecretManager must be provided.");
    }

    public async Task<string?> GetSecretAsync(string secretName, CancellationToken ct = default)
    {
        foreach (var manager in _managers)
        {
            try
            {
                var value = await manager.GetSecretAsync(secretName, ct);
                if (value is not null)
                {
                    _logger.LogDebug("Secret '{Name}' found in {Provider}",
                        secretName, manager.GetType().Name);
                    return value;
                }
            }
            catch (SecretNotFoundException)
            {
                // Not found here — try next provider
                _logger.LogDebug("Secret '{Name}' not found in {Provider}, trying next",
                    secretName, manager.GetType().Name);
            }
            catch (Exception ex)
            {
                // Provider error — log and try next, don't crash
                _logger.LogWarning(ex, "Error fetching '{Name}' from {Provider}, trying next",
                    secretName, manager.GetType().Name);
            }
        }

        // Exhausted all providers
        throw new SecretNotFoundException(secretName);
    }

    // Writes always go to the PRIMARY (first) provider only
    public Task SetSecretAsync(string secretName, string value, CancellationToken ct = default)
        => _managers[0].SetSecretAsync(secretName, value, ct);
}

Key design decisions:

SecretNotFoundException from a provider means "not here, try next" — it's expected and swallowed
Any other exception (network error, auth failure) is logged as a warning and the chain continues — one broken provider doesn't block fallbacks
Writes go to _managers[0] (primary) only — writing to all providers would create sync problems

Part 5 — ASP.NET Core Integration

`AddSecretVault` — The DI Extension Method

public static IServiceCollection AddSecretVault(
    this IServiceCollection services,
    ISecretManager manager,
    Action<CachedSecretManagerOptions>? configureCaching = null)
{
    if (configureCaching is not null)
    {
        services.AddMemoryCache();

        // Register the CachedSecretManager as a concrete singleton
        services.AddSingleton(sp =>
        {
            var options = new CachedSecretManagerOptions();
            configureCaching(options);   // apply caller's configuration
            var cache = sp.GetRequiredService<IMemoryCache>();
            var logger = sp.GetRequiredService<ILogger<CachedSecretManager>>();
            return new CachedSecretManager(manager, cache, logger, options);
        });

        // Map ISecretManager → CachedSecretManager
        // Any class that injects ISecretManager gets the cached version
        services.AddSingleton<ISecretManager>(
            sp => sp.GetRequiredService<CachedSecretManager>());
    }
    else
    {
        // No caching — register the raw provider directly
        services.AddSingleton<ISecretManager>(manager);
    }

    return services;
}

The key line is services.AddSingleton<ISecretManager>(sp => sp.GetRequiredService<CachedSecretManager>()). This creates an alias in the DI container — ISecretManager resolves to CachedSecretManager, which itself wraps AwsSecretManager. Your services inject ISecretManager and silently get three layers of behavior.

`IConfiguration` Integration

// The source tells the config system how to build our provider
public class SecretVaultConfigurationSource : IConfigurationSource
{
    private readonly ISecretManager _manager;
    private readonly IEnumerable<string> _secretNames;

    public IConfigurationProvider Build(IConfigurationBuilder builder)
        => new SecretVaultConfigurationProvider(_manager, _secretNames);
}

// The provider does the actual loading
public class SecretVaultConfigurationProvider : ConfigurationProvider
{
    public override void Load()
    {
        // Fetch all secrets synchronously at startup
        var secrets = _manager.GetSecretsAsync(_secretNames).GetAwaiter().GetResult();

        // Store in the Data dictionary — this is what IConfiguration reads from
        Data = secrets
            .Where(kvp => kvp.Value is not null)
            .ToDictionary(kvp => kvp.Key, kvp => kvp.Value!);
    }
}

Why .GetAwaiter().GetResult() instead of await? IConfigurationProvider.Load() is synchronous — it's called during host startup before the async pipeline is running. This is one of the few legitimate places to block on async code in .NET.

Health Check

public class SecretVaultHealthCheck : IHealthCheck
{
    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken ct = default)
    {
        try
        {
            await _manager.GetSecretAsync("__healthcheck__", ct);
            return HealthCheckResult.Healthy("Secret provider is reachable.");
        }
        catch (SecretNotFoundException)
        {
            // Provider is reachable — the probe secret just doesn't exist, which is fine
            return HealthCheckResult.Healthy("Secret provider is reachable.");
        }
        catch (SecretProviderUnavailableException ex)
        {
            return HealthCheckResult.Unhealthy("Secret provider is unavailable.", ex);
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Degraded("Unexpected error.", ex);
        }
    }
}

The __healthcheck__ probe secret almost certainly doesn't exist — and that's intentional. SecretNotFoundException proves the provider is reachable and responding. Only SecretProviderUnavailableException (network issue, auth failure) marks the check as unhealthy.

Part 6 — Tests

public class CachedSecretManagerTests
{
    private readonly ISecretManager _inner = Substitute.For<ISecretManager>();
    private readonly IMemoryCache _cache = new MemoryCache(new MemoryCacheOptions());
    private readonly CachedSecretManager _sut;

    [Fact]
    public async Task GetSecretAsync_SecondCall_ReturnsCachedValue()
    {
        _inner.GetSecretAsync("my-secret", default).Returns("super-secret");

        await _sut.GetSecretAsync("my-secret");  // first call — hits inner
        await _sut.GetSecretAsync("my-secret");  // second call — from cache

        // Inner was only called ONCE despite two GetSecretAsync calls
        await _inner.Received(1).GetSecretAsync("my-secret", default);
    }

    [Fact]
    public async Task SetSecretAsync_InvalidatesCache()
    {
        _inner.GetSecretAsync("my-secret", default).Returns("old-value", "new-value");

        await _sut.GetSecretAsync("my-secret");         // caches "old-value"
        await _sut.SetSecretAsync("my-secret", "new-value"); // invalidates cache
        var result = await _sut.GetSecretAsync("my-secret"); // re-fetches "new-value"

        result.Should().Be("new-value");
        await _inner.Received(2).GetSecretAsync("my-secret", default);
    }
}

public class ChainedSecretManagerTests
{
    [Fact]
    public async Task GetSecretAsync_FallsBackToSecondary_WhenPrimaryThrowsNotFound()
    {
        _primary.GetSecretAsync("key", default)
            .Throws(new SecretNotFoundException("key"));
        _fallback.GetSecretAsync("key", default).Returns("from-fallback");

        var result = await _sut.GetSecretAsync("key");

        result.Should().Be("from-fallback");
    }
}

NSubstitute is used for mocking — Substitute.For<ISecretManager>() creates a fake implementation that returns configured values. FluentAssertions makes assertions read like English. Real MemoryCache is used instead of a mock because testing with the actual cache catches real caching bugs that a mock would hide.

Part 7 — GitHub Actions CI/CD

CI (`ci.yml`) — Every push and PR

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '9.0.x'
      - run: dotnet restore SecretVault.sln
      - run: dotnet build SecretVault.sln --configuration Release --no-restore
      - run: dotnet test SecretVault.sln --configuration Release --no-build

Publish (`publish.yml`) — Tag a version, ship everything

on:
  push:
    tags:
      - 'v*.*.*'   # v1.0.0, v1.2.3, etc.

steps:
  - name: Extract version from tag
    id: version
    run: echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
    # v1.0.0 → 1.0.0 (strips the "v" prefix for NuGet)

  - name: Pack all packages
    run: |
      dotnet pack src/SecretVault.Core/SecretVault.Core.csproj \
        --configuration Release \
        /p:Version=${{ steps.version.outputs.VERSION }} \
        --output ./nupkgs
      # ... repeated for all 6 packages

  - name: Publish to NuGet
    run: |
      dotnet nuget push ./nupkgs/*.nupkg \
        --api-key ${{ secrets.NUGET_API_KEY }} \
        --source https://api.nuget.org/v3/index.json \
        --skip-duplicate

${GITHUB_REF_NAME#v} is a bash parameter expansion — it strips the v prefix from the tag name so v1.0.0 becomes 1.0.0, which is what NuGet expects for version numbers.

--skip-duplicate prevents the pipeline from failing if a package version was already published (e.g. if you re-run the workflow).

To release:

git tag v1.0.0
git push origin v1.0.0
# GitHub Actions handles the rest automatically

Summary — Design Patterns Used

Pattern	Where	Why
Interface segregation	`ISecretManager` + `ISecretRotationManager`	Rotation is optional — don't force it on basic consumers
Decorator	`CachedSecretManager`	Add caching without modifying providers
Chain of responsibility	`ChainedSecretManager`	Fallback across providers without coupling
Factory via DI	`AddSecretVault` extension	Compose the full object graph in one place
Normalized exceptions	Per-provider catch/rethrow	Shield callers from SDK-specific error types
Cache-aside	`CachedSecretManager.GetSecretAsync`	Lazy populate, invalidate on write
Configuration provider	`SecretVaultConfigurationSource`	Plug into the standard .NET config pipeline

View the full source on GitHub · NuGet Packages

I Built an AI-Powered Dead Code Detector for VS Code

Naimul Karim — Tue, 12 May 2026 03:10:26 +0000

We've all been there. You're reading through a codebase and you spot it — a feature flag that's been set to false for two years, a function exported from a module that nothing ever imports, a block of logic sitting underneath a return statement that will never, ever run.

ESLint catches unused variables. TypeScript catches type mismatches. But dead business logic? That's a different beast — and that's what I built this extension to hunt.

What Is "Dead Code" Really?

Most linters think dead code = unused variable. But in production codebases the real offenders are:

1. Unreachable Logic
Code that can never execute — not because of a syntax issue, but because of your business logic:

function calculateDiscount(price: number, userType: string): number {
  if (userType === "admin") {
    return price * 0;
  }
  return price * 0.9;

  // Never reached — the return above always fires
  const bonus = price * 0.05;
  console.log("Applying bonus:", bonus);
  return price - bonus;
}

2. Unused APIs and Functions
Exported functions nobody calls. Classes defined and never instantiated. Entire modules orphaned after a refactor:

// Exported but nothing in the codebase ever calls this
export class OldReportGenerator {
  generate(data: any[]) {
    return data.map((d) => JSON.stringify(d)).join("\n");
  }
  exportToCsv(data: any[]) {
    return data.join(",");
  }
}

3. Obsolete Feature Flags
The slowest-burning dead code. A flag gets hardcoded, the ticket gets closed, and the condition guards code that either always runs or never runs:

const FEATURE_DARK_MODE = false;    // 🚩 Has been false for 18 months
const USE_NEW_CHECKOUT = true;      // 🚩 Always true — the else branch is dead

if (FEATURE_DARK_MODE) {
  applyDarkTheme(); //  Never runs
}

if (USE_NEW_CHECKOUT) {
  showNewCheckout();
} else {
  showLegacyCheckout(); //  Never runs
  trackLegacyCheckoutEvent();
}

Traditional static analysis tools struggle with these because they require understanding intent, not just syntax.

The Solution: AI-Powered Analysis

I built Dead Code Detector — a VS Code extension that sends your file to Claude (via the Anthropic API) with a carefully engineered prompt, gets back a structured JSON response, and renders the results as both inline diagnostics and a filterable results panel.

GitHub: github.com/naimulkarim/dead-code-detector

Here's what it looks like in action:

🔴 Inline squiggles in the editor (appears in your Problems panel)
📊 A results panel that opens beside your file with filtering, severity badges, and jump-to-line

How It Works

The Prompt Engineering

The heart of the extension is the system prompt in src/analyzer.ts. Getting an LLM to return reliable, parseable structured data requires being very explicit:

const SYSTEM_PROMPT = `You are an expert static analysis tool specializing in dead code detection. 
Analyze the provided source code and identify:

1. **Unreachable Business Logic** — code after unconditional returns, inside impossible 
   conditions (e.g. if (false), if (1 === 2)), catch blocks that swallow everything, etc.

2. **Unused APIs / Functions** — exported or defined functions/classes/variables that appear 
   to never be called or referenced within the file.

3. **Obsolete Feature Flags** — boolean constants or config checks that are hardcoded to 
   true/false, e.g. const FEATURE_X = false used in conditions.

Respond ONLY with a JSON array (no markdown, no preamble). Each item must have:
{
  "category": "unreachable-logic" | "unused-api" | "obsolete-feature-flag" | "dead-code",
  "message": "Short one-line summary (< 80 chars)",
  "explanation": "2-3 sentences explaining why this is dead/obsolete code",
  "suggestion": "What to do — remove, refactor, or clean up",
  "line": <integer line number where the issue starts, or null>,
  "severity": "high" | "medium" | "low"
}

Return [] if no issues found.`;

Key decisions here:

"Respond ONLY with a JSON array" — no preamble, no markdown fences in the model's thinking. We strip any stray fences client-side as a safety net.
Explicit schema — defining every field prevents the model from inventing its own structure.
"Return [] if no issues found" — so a clean file doesn't produce a parse error.

Calling the API

const response = await fetch("https://api.anthropic.com/v1/messages", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": apiKey,
    "anthropic-version": "2023-06-01",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-20250514",
    max_tokens: 2048,
    system: SYSTEM_PROMPT,
    messages: [{ role: "user", content: userMessage }],
  }),
});

const data = await response.json();
const text = data.content
  .filter((b) => b.type === "text")
  .map((b) => b.text)
  .join("");

// Strip possible markdown fences before parsing
const clean = text.replace(/```
{% endraw %}
json|
{% raw %}
```/g, "").trim();
const results = JSON.parse(clean);

We cap the file at 12,000 characters before sending — enough for most real-world files without burning tokens unnecessarily.

Turning Results into VS Code Diagnostics

Once we have the JSON array back, we map each issue to a vscode.Diagnostic so it shows up inline in the editor and the Problems panel:

function applyDiagnostics(doc: vscode.TextDocument, results: DeadCodeResult[]) {
  const diagnostics = results.map((result) => {
    const line = Math.max(0, (result.line ?? 1) - 1);
    const range = doc.lineAt(Math.min(line, doc.lineCount - 1)).range;
    const diag = new vscode.Diagnostic(
      range,
      `[${result.category}] ${result.message}`,
      vscode.DiagnosticSeverity.Warning
    );
    diag.source = "Dead Code AI";
    diag.code = result.category;
    return diag;
  });

  diagnosticCollection.set(doc.uri, diagnostics);
}

The Results Panel

Results also open in a Webview panel beside your editor. It's filterable by category and sortable by severity, with a Jump to Line button on each card that snaps the cursor to the exact location in your file.

// The webview posts a message back to the extension host
ResultsPanel.currentPanel.webview.onDidReceiveMessage(async (msg) => {
  if (msg.command === "jumpTo") {
    const editor = vscode.window.visibleTextEditors[0];
    const pos = new vscode.Position(Math.max(0, msg.line - 1), 0);
    editor.selection = new vscode.Selection(pos, pos);
    editor.revealRange(
      new vscode.Range(pos, pos),
      vscode.TextEditorRevealType.InCenter
    );
  }
});

Features

✅ Detects unreachable logic, unused APIs, and obsolete feature flags
✅ Works on JS, TS, JSX, TSX, and Python
✅ Inline squiggles in the editor via VS Code's Diagnostics API
✅ Filterable results panel with severity badges and jump-to-line
✅ Workspace-wide scan (with a confirmation prompt for large repos)
✅ Configurable severity level (error / warning / information / hint)
✅ Toggle individual checks on/off in settings
✅ Works via environment variable (ANTHROPIC_API_KEY) or Settings UI

Installation & Setup

Prerequisites

Node.js v18+
VS Code 1.85+
An Anthropic API key — get one at console.anthropic.com

From GitHub

# Clone the repo
git clone https://github.com/naimulkarim/dead-code-detector.git
cd dead-code-detector

# Install dependencies
npm install

# Open in VS Code
code .

Then press F5 — this opens a new Extension Development Host window with the extension loaded.

Add Your API Key

Option A — Settings UI (recommended):

Open Settings (Cmd+, on Mac / Ctrl+, on Windows)
Search for Dead Code
Paste your key into Dead Code Detector: Anthropic Api Key

Option B — Environment variable:

export ANTHROPIC_API_KEY=sk-ant-api03-...

Usage

Action	Shortcut / How
Analyze current file	`Cmd+Shift+D` / `Ctrl+Shift+D`
Analyze current file	Right-click in editor → Dead Code: Analyze Current File
Analyze entire workspace	Command Palette → Dead Code: Analyze Entire Workspace
Clear diagnostics	Command Palette → Dead Code: Clear All Diagnostics

Test It Immediately

The repo includes sample-test.ts — a file pre-loaded with intentional dead code of all three types. Open it and hit Cmd+Shift+D to see the extension in action right away.

Configuration

// .vscode/settings.json or user settings
{
  "deadCode.anthropicApiKey": "sk-ant-...",
  "deadCode.severity": "warning",
  "deadCode.checks": {
    "unreachableLogic": true,
    "unusedApis": true,
    "obsoleteFeatureFlags": true
  }
}

Architecture Overview

User triggers Cmd+Shift+D
        ↓
extension.ts
  → reads active document text
  → reads enabled checks from config
        ↓
analyzer.ts
  → builds user prompt with language + filename + code
  → POST /v1/messages → Claude Sonnet
  → strips markdown fences, JSON.parse()
  → returns DeadCodeResult[]
        ↓
extension.ts
  → vscode.DiagnosticCollection.set() → squiggles in editor
        ↓
resultsPanel.ts
  → Webview HTML panel with filter buttons + severity cards
  → postMessage() → jump-to-line on click

What's Next

A few things I want to add:

[ ] Quick Fix actions — a code action that lets you delete the dead code with one click
[ ] Sidebar tree view — persistent panel showing all issues across the workspace
[ ] Git blame integration — show who added the dead code and when
[ ] Caching — skip re-analyzing files that haven't changed since last scan
[ ] More languages — Go, Ruby, Rust

PRs and issues are very welcome at github.com/naimulkarim/dead-code-detector.

DEV Community: Naimul Karim

Build Smarter AI Agents: Use Deterministic Code Before Calling an LLM

The problem: asking an LLM to solve the same thing repeatedly

Turn a known decision into deterministic code

What do we mean by deterministic code?

Two principles for designing efficient AI systems

1. If you can reliably express a decision as rules, use code

2. If an LLM keeps solving the same problem, consider turning the solution into code

A hybrid architecture: deterministic code plus LLM reasoning

AI-assisted development makes this approach easier

Does this mean future AI agents will use fewer LLM calls?

Final thoughts

Build a Simple E-commerce MVP with AI: A Step-by-Step Guide

The example: QuickCart

The plan

Before you start

The trick I use in every prompt

Step 1: The PRD

Step 2: The screen flow

Step 3: The tech stack

Step 4: The design system

See it before you build it

Step 5: The database schema and API

Step 6: The implementation plan

Step 7: The part you have to do yourself

Step 8: Build it

Step 9: Get a second opinion

Step 10: Test it and ship it

What I'd tell my past self

Wrapping up

A Practical Guide to CLAUDE.md, Permissions, Plan Mode, Skills, and Sub-Agents

First, what makes Claude Code different from chatting with Claude?

Step 1: Give it a memory with CLAUDE.md (or AGENTS.md)

Step 2: Control what it can do with permissions

Step 3: Use plan mode when the decision is expensive

Step 4: Turn repeated processes into skills

Step 5: Hand off investigations to sub-agents

Step 6: Spawn a sub-agent to review the code

Triage before you fix

The progression that matters

Key take aways

Building Modern Scalable Applications: Understanding Docker, Kubernetes, Redis, Kafka & Prometheus

1. Docker: Package the application consistently

2. ECS and Kubernetes: Run and manage containers

Amazon ECS

Kubernetes

3. Terraform: Define infrastructure as code

4. DNS and load balancing: Route incoming requests

5. PostgreSQL: Store the source-of-truth data

6. Redis: Reduce repeated database work with caching

The challenge: cache invalidation

7. OpenSearch: Handle more advanced search requirements

8. Amazon S3: Store files outside the relational database

9. Message queues: Move slow work out of the request

Acknowledgements and retries

10. Kafka: Distribute events to multiple consumers

11. CI/CD and Amazon ECR: Deliver code changes reliably

12. Helm: Manage Kubernetes application configuration

13. Argo CD: Use GitOps to keep deployments aligned

14. Prometheus and Grafana: Understand application health

15. OpenTelemetry: Instrument and follow requests across services

16. Bringing the pieces together

17. Every technology solves a problem—and adds responsibility

Conclusion

Further reading

How to Debug Android Chrome Browser Logs from a Windows Laptop

Part 1: Set Up Android Remote Debugging

Step 1: Enable Developer Options on Android

Google Pixel

Other Android Devices

Step 2: Enable USB Debugging

Step 3: Connect the Android Phone to Windows

Keep the phone unlocked

Step 4: Authorize USB Debugging

Part 2: Open the Website on Android Chrome

Step 5: Open Chrome on the Android Device

Part 3: Connect Chrome DevTools

Step 6: Open Chrome Remote Debugging on Windows

Part 4: Debug the Android Website

Console

Part 5: Troubleshooting `Pending authentication`

Step 2: Open Command Prompt in `platform-tools`