@mkappelhof/agent-instructions 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1 +1,17 @@
 # @mkappelhof/agent-instructions
+
+## 1.1.0
+
+### Minor Changes
+
+- 3c4c6b4: Add `nest.md` with general best-practice conventions for NestJS services (project structure, DI, DTOs/validation, error handling, config/logging, testing).
+
+### Patch Changes
+
+- 3c4c6b4: Make `base.md` a generic, standalone baseline instead of assuming it's always paired with this repo's other `@mkappelhof/*` config packages. Following a matching config package's `AGENTS.md` is now framed as conditional on the project actually using it, not assumed.
+
+## 1.0.1
+
+### Patch Changes
+
+- eb2577f: Add new configs

package/README.md

@@ -1,17 +1,21 @@
 # Shared agent instructions
 
 Project-level instructions for AI coding agents, covering code structure and conventions rather
-than tool configuration. Pair them with the `AGENTS.md` files shipped by the config packages in
-this repo, which describe the tool rules.
-
-| File | For |
-| --- | --- |
-| `base.md` | Every project: verifying instead of assuming, workflow, git, imports, TypeScript, design tokens, versioning |
-| `react.md` | React and Next.js projects (components, contexts, i18next, SCSS modules, Vitest) |
-| `astro.md` | Static Astro sites (rendering, styling, data, images) |
-
-`react.md` and `astro.md` both tell agents to read `base.md` first, so you only need to reference
-the file for your project type.
+than tool configuration. If the project also uses one of this repo's config packages (TypeScript,
+Biome, ESLint, Stylelint), pair these with the `AGENTS.md` it ships, which describes that tool's
+rules — but these files don't assume that pairing, and `base.md` works as generic baseline
+instructions on its own for a project that doesn't match any of the more specific files below.
+
+| File       | For                                                                                                                  |
+| ---------- | -------------------------------------------------------------------------------------------------------------------- |
+| `base.md`  | Any project, any stack: verifying instead of assuming, workflow, git, imports, TypeScript, design tokens, versioning |
+| `react.md` | React and Next.js projects (components, contexts, i18next, SCSS modules, Vitest)                                     |
+| `astro.md` | Static Astro sites (rendering, styling, data, images)                                                                |
+| `nest.md`  | NestJS services (modules, DI, DTOs/validation, error handling, testing)                                              |
+
+`react.md`, `astro.md` and `nest.md` all tell agents to read `base.md` first, so you only need to
+reference the file for your project type. For a project that's none of these (a plain script,
+a different framework, etc.), reference `base.md` directly.
 
 ## Installation
 

package/base.md

@@ -1,10 +1,18 @@
 # Base — agent instructions
 
-Conventions that apply to every project type. `react.md` and `astro.md` build on this file. Where
-the project's own `AGENTS.md` says something different, the project wins.
-
-Tool rules (TypeScript, Biome, Stylelint) are described in the `AGENTS.md` of the matching
-`@mkappelhof/*` config package. Follow those as well.
+My personal baseline conventions for any project I work on, regardless of stack and regardless of
+whether the project uses any other `@mkappelhof/*` package. `react.md`, `astro.md` and `nest.md`
+build on this file for their respective project types, but this file is also meant to stand alone
+as generic `AGENTS.md` content for projects that don't match one of those.
+
+This file is a starting point, not a mandate: where the project's own `AGENTS.md` (or anything the
+user says) differs from what's here, that project-specific instruction wins.
+
+If the project happens to use one of my shared `@mkappelhof/*` config packages (for TypeScript,
+linting, formatting, etc.), that package's own `AGENTS.md` describes the rules its tool enforces —
+follow those too. Don't assume one is in use, though; check the project's `package.json` and
+config files (`tsconfig.json`, `.eslintrc*`, `biome.json`, `.stylelintrc*`, ...) to see what
+tooling is actually there before applying tool-specific conventions from anywhere.
 
 ## Don't assume, verify or ask
 

package/nest.md

@@ -0,0 +1,53 @@
+# NestJS — agent instructions
+
+Conventions for NestJS services written in TypeScript. Everything in [`base.md`](./base.md)
+applies as well (its CSS/design-token sections just won't come up in a backend service); read it
+first.
+
+## Project structure
+
+- Organize by feature module under `src/<feature>/`, each with its own controller, service,
+  module and DTOs — the shape `nest g resource` / `nest g module|controller|service` produces.
+- One class per file, named `<name>.<type>.ts` (`users.controller.ts`, `users.service.ts`,
+  `users.module.ts`).
+- DTOs live in a `dto/` folder inside the feature module, one class per file
+  (`dto/create-user.dto.ts`).
+
+## Modules & dependency injection
+
+- Keep controllers thin: parse input, delegate to a service, shape the response. Business logic
+  belongs in services, not controllers.
+- Inject dependencies through constructor parameter properties
+  (`constructor(private readonly usersService: UsersService) {}`), not property injection or
+  manual `new`.
+- Depend on Nest's DI container for anything registered as a provider; don't import a service and
+  instantiate it yourself.
+
+## DTOs & validation
+
+- Validate every request body/query/param with a DTO class using `class-validator` decorators
+  (`@IsString()`, `@IsOptional()`, etc.), not manual checks in the controller.
+- Enable a global `ValidationPipe` (with `whitelist: true`) in `main.ts` instead of adding it
+  per-route.
+- Shape what a controller returns with a response DTO or `class-transformer`'s
+  `@Expose()`/`@Exclude()`, instead of returning entity/ORM objects straight to the client.
+
+## Error handling
+
+- Throw Nest's built-in HTTP exceptions (`NotFoundException`, `BadRequestException`, etc.) instead
+  of returning error objects or throwing a plain `Error`.
+- For error formatting that applies across many routes, use an `ExceptionFilter` instead of
+  repeating try/catch in every controller.
+
+## Configuration & logging
+
+- Read environment values through `@nestjs/config`'s `ConfigService`, not `process.env` scattered
+  through the codebase.
+- Log through Nest's built-in `Logger`, not `console.log`.
+
+## Testing
+
+- Build tests with `Test.createTestingModule` and override providers with mocks, rather than
+  instantiating classes by hand.
+- Co-locate unit tests with their source as `*.spec.ts`. Keep end-to-end tests that exercise the
+  HTTP layer in `test/` as `*.e2e-spec.ts`.

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "@mkappelhof/agent-instructions",
-  "version": "1.0.0",
-  "description": "Shared instructions for AI coding agents working on React/Next.js and Astro projects",
+  "version": "1.1.0",
+  "description": "Shared instructions for AI coding agents working on React/Next.js, Astro and NestJS projects",
   "exports": {
     "./base.md": "./base.md",
     "./react.md": "./react.md",
     "./astro.md": "./astro.md",
+    "./nest.md": "./nest.md",
     "./package.json": "./package.json"
   },
   "files": [
     "base.md",
     "react.md",
     "astro.md",
+    "nest.md",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -27,6 +29,7 @@
     "ai",
     "react",
     "nextjs",
-    "astro"
+    "astro",
+    "nestjs"
   ]
 }