DEV Community: Azad Mohamed

How to Structure a NestJS Backend for AI-Assisted Development

Azad Mohamed — Sat, 17 Oct 2026 20:05:56 +0000

AI coding agents are good at writing NestJS code and bad at guessing your NestJS conventions. Left alone, they put queries in controllers, return entities straight from the database, add a fourth way of throwing errors, and cheerfully offer to run migration:run against whatever database your .env points at.

The fix is not a cleverer prompt. It's a repository that states its rules where agents read them, makes correct changes cheap to verify, and enforces the few rules that must never be broken. Here's the structure I use. None of it needs a particular agent.

1. One instruction file, and only one

Every major agent now reads a project instruction file. Codex, Cursor, GitHub Copilot and Gemini CLI (with one setting) read AGENTS.md. Claude Code reads CLAUDE.md, which can import another file. So:

<!-- CLAUDE.md -->
@AGENTS.md

## Claude Code specifics
(skills, subagents, permission rules: only what is genuinely Claude-specific)

// .gemini/settings.json
{ "context": { "fileName": ["AGENTS.md"] } }

Rules live in AGENTS.md only. The day you have the same rule in two files, they start to drift, and some tools (Copilot CLI, for one) merge every instruction file they find without a precedence order. Keep AGENTS.md short (a project map, commands, conventions, safety rules, report format) and link to docs/ for detail.

2. Write stop rules, not style advice

"Write clean code" changes nothing. What changes behaviour is a short list of things the agent must not do, written as rules with the exact words you want back:

## Stop rules

1. Do not generate, run or revert migrations until the user tells you to in this conversation.
   An entity change is not permission. Make the code change and report:
   "Schema change detected. Migration required. Not generated or run: no explicit approval."
2. Do not run or edit seeds until the user tells you to.
3. Do not format code. The pre-commit hook formats staged files; CI checks formatting.

Rule 3 is a cost rule: formatting runs burn agent time and produce noisy diffs, and Husky + lint-staged already do it on every commit.

3. Make the architecture boring and stated

Agents copy what they see. If the codebase has one pattern, they copy that one. Pick an explicit structure and write it down:

src/<feature>/
  controllers/   HTTP only: routing, guards, Swagger decorators
  services/      business rules; one class per responsibility
  dto/           request DTOs (class-validator, length limits) and response DTOs
  entities/      the data model; no queries, HTTP, email or JWT logic

Then the dependency rule in one line: Controller → Service → Repository<Entity>. Other modules inject the owning service, never another module's repository. And a few "never" rules that agents otherwise break constantly:

Responses map entities through ResponseDto.fromEntity(); never return an entity (that's how password hashes end up in JSON).
User-owned data is looked up by the authenticated ID from @CurrentUser(), never by an ID from the request alone.
Clients never set server-owned fields (status, verification state, roles).

A global ValidationPipe with whitelist: true, forbidNonWhitelisted: true backs the last rule up mechanically: a DTO that doesn't declare status can't receive it.

4. One error contract

Give the agent exactly one way to fail:

export abstract class AppException extends Error { /* status + stable code */ }
export class NotFoundError extends AppException {}
export class ConflictError extends AppException {}
// ...

throw new ConflictError('EMAIL_ALREADY_REGISTERED', 'Email is already registered');

A single global exception filter turns every error, including unexpected ones, into the same shape:

{ "statusCode": 409, "code": "EMAIL_ALREADY_REGISTERED", "message": "...",
  "path": "/api/v1/auth/register", "requestId": "6f1c...", "timestamp": "..." }

Stable UPPER_SNAKE codes give agents (and frontends) something to assert on, and the filter is the one place that guarantees no SQL, stack trace or SMTP detail leaks.

5. Make verification cheap, or it won't happen

An agent will run the checks you make easy. If tests need a database, Docker and seed data, the agent either skips them or starts containers you didn't ask for. So make the default suites infrastructure-free:

Unit tests construct services directly with a small in-memory repository that implements only the TypeORM methods your services use:

  /** Minimal in-memory stand-in for the TypeORM repository methods used by the services. */
  export class MockRepository<T extends { id: string }> {
    readonly items = new Map<string, T>();
    create(data: Partial<T> = {}): T { /* ... */ }
    async save(entity: Partial<T>): Promise<T> { /* ... */ }
    // findOne, findAndCount, update... only what's used
  }

E2E tests boot the real AppModule with the real pipes, guards, filters and throttler, and override only the repositories and the mail service. That tests authorization and validation where the bugs actually are, in about ten seconds, with no database.

Then tell the agent the exact commands, narrowest first (npx jest <path>), and that a red test is fixed for a real reason, never by weakening the assertion.

Be honest about the gap: in-memory repositories don't test SQL, constraints or cascades. Say so in docs/testing.md, and check migrations by hand (up, down, up) against a disposable PostgreSQL before a release.

6. Enforce the rules that matter; write down the rest

Written rules are followed most of the time. For the few operations that can destroy data, add enforcement your tool supports. In Claude Code, ask permission rules prompt before matching commands even in permissive modes:

{
  "permissions": {
    "ask": ["Bash(npm run migration:*)", "Bash(npm run seed *)", "Bash(psql *)",
            "Bash(docker compose down *)", "Bash(git push *)"],
    "deny": ["Read(**/.env)", "Read(**/.env.production)"]
  }
}

Know the limits: these rules match command text. A script that runs a migration indirectly isn't caught, and a deny on reading .env doesn't stop code that opens the file. For other agents, configure their command approval for the same commands.

7. Demand a fixed report

The most useful line in my AGENTS.md is the report format:

Implemented       what changed and why
Files changed     paths
Verification      commands actually run and their actual results
Not performed     e.g. migration generation, seed execution, Docker, deploy
Unverified        anything you could not check
Never claim a command passed if you did not run it.

It turns "Done! Everything works" into something you can check in thirty seconds, and the "Not performed" line is where the pending migration shows up instead of silently happening.

8. Turn recurring jobs into procedures

When you notice you're giving the same multi-step instruction for the third time, make it a file. In Claude Code these are skills (.claude/skills/<name>/SKILL.md), loaded on demand; for other agents the same Markdown works as "follow .claude/skills/debug/SKILL.md". Good candidates in a NestJS API:

generate: inspect an existing module first, reuse before creating, add tests, report.
database-change: check entity conventions, decide whether a migration is needed, review an existing migration's down(), and never generate one without a request.
debug: map symptoms to the right file (400 property X should not exist → the DTO is missing a field), reproduce with a database-free test, fix at the root.

Name them so they don't shadow built-in commands (review-change, not review).

The short version

One AGENTS.md; tool files import it.
Stop rules with exact words, not style advice.
One structure, one dependency direction, a few explicit "nevers".
One error class hierarchy and one filter.
Default test suites that need no infrastructure.
Tool-enforced prompts for destructive commands.
A fixed report that separates "verified" from "not performed".
Recurring tasks as procedure files.

I've packaged this structure, with a complete NestJS 11 + PostgreSQL implementation (auth, admin API, migration, 96 tests, Docker, and the agent files above), as a paid starter kit. If you'd rather start from it than build your own, it's here: NestJS Production Starter Kit for AI Coding Agents.

I Kept Forgetting to Drink Water While Coding, So I Built Kairo

Azad Mohamed — Wed, 26 Aug 2026 18:22:42 +0000

I spend a lot of time in front of a computer.

And like probably a lot of developers, when I'm deep into work, I completely forget about everything around me.

Drink water? Forgot.

Take a break? Forgot.

Look away from the screen? Forgot.

Move around for a few minutes? Maybe after another three hours. 😅

Living in the UAE makes this even easier. It's hot outside for a good part of the year, so it's very easy to stay indoors, sit in front of a screen, turn on the AC, and just keep working.

At some point I thought:

Why don't I just build something to remind me?

So I built Kairo.

What is Kairo?

Kairo is a small desktop companion designed to help build healthier computer habits.

The idea is simple:

💧 Remind me to drink water
👀 Remind me to rest my eyes
🚶 Remind me to take breaks
🧘 Encourage healthier working habits
📊 Keep track of what I've actually been doing

I wanted something that felt less like a notification from an operating system and more like a small companion sitting alongside me while I work.

That's where the animated character comes in.

I wanted it to be private

One thing I didn't want was another productivity application that required an account and sent all my activity to some server.

So I designed Kairo around an offline-first approach.

The core application works locally and stores its data on the machine.

AI is also completely optional.

If you want AI-powered coaching, Kairo can connect to providers such as Ollama or LM Studio, so you can run the AI locally instead of sending your data to a cloud service.

The application should still work perfectly fine without AI.

Why I built it

Honestly, this wasn't originally meant to become a big open-source project.

I built it because I needed it.

I kept noticing the same pattern in my own work:

Start coding → get focused → lose track of time → forget water → forget breaks → realize hours have passed.

If Kairo can interrupt that cycle even a little, then it has already done what I wanted.

A little bit about the engineering

Although the idea is simple, I wanted to use the project to experiment with building a proper desktop application.

Kairo is built with Flutter and is currently focused on macOS.

Some of the things I'm working with include:

Flutter desktop
SQLite for local persistence
Event-driven communication
Modular packages
Native desktop integration
Offline-first architecture
Optional AI providers
Local AI through OpenAI-compatible endpoints

One design decision I'm particularly happy with is keeping AI out of the critical reminder path.

The reminder system shouldn't stop working just because an AI provider is unavailable.

AI should enhance the experience, not become a dependency for the basic functionality.

It's still a work in progress

There are plenty of things I want to improve.

I'm still figuring out:

Better reminder behaviour
More useful habit insights
Better AI coaching
More customization
Improving the desktop experience
Supporting more platforms

And this is where I'd really like some feedback.

If you spend most of your day working at a computer:

What would actually help you build healthier working habits?

Not another productivity dashboard.

Not another app asking you to track 20 things.

Just something that quietly helps you remember the basic things we tend to forget when we're focused.

Try Kairo

The project is open source:

GitHub: https://github.com/azadhmhd/kairo

If you find it useful, give it a try.

And if you have ideas, suggestions, or even things you think I've approached badly, I'd love to hear them.

I built Kairo for myself, but maybe it can become something useful for other developers too.

Maybe we can build a healthier workspace together.