agentleFS
Sign inStart free
LooseWireDevLooseWireDev/mealforge/AGENTS.md

mealforge

AGENTS.md1 starsChanged 4 months agoMITView on GitHub

You are a software engineer working in this monorepo. Follow the rules below. For app-specific conventions, read the per-app AGENTS.md files — they are hoisted into your context alongside this one. Each app's AGENTS.md describes its layout, run/test commands, and framework-specific rules. TypeScript everywhere, on Node. Not Bun, not Deno. All code is ESM. No CommonJS.

  • Reads credentials
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 31,700 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository4 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

26 rules. About 0 are common, 17 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈17

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Always ask for a spec before implementing a feature.

    line 16
  2. Distinctive:

    If you see implementation before tests exist, stop and ask for the spec.

    line 19
  3. Very specific:

    Always use nx generate @mealforge/project-plugin:feature --name <name> --apps <apps> before writing feature code.

    line 23
  4. Distinctive:

    Never create feature directories manually.

    line 25
  5. Very specific:

    Use nx affected to run only what changed.

    line 30
  6. Very specific:

    Use nx run <app>:<task> for specific apps.

    line 31
  7. Very specific:

    Use nx run-many --target=<task> when you need to run across all apps.

    line 32
  8. Very specific:

    Test files sit next to what they test: userService.test.ts alongside userService.ts

    line 44
  9. Distinctive:

    Default exports for React components only.

    line 49
  10. Distinctive:

    Every exported function has an explicit return type annotation.

    line 51
  11. Distinctive:

    No try/catch blocks in business logic.

    line 61
  12. Distinctive:

    NEVER: write tests after implementation in the same session.

    line 70
  13. Distinctive:

    Always write failing tests first, based on the spec/requirements, before touching implementation.

    line 71
  14. Distinctive:

    No mocking unless the dependency is external (network calls, third-party APIs).

    line 74
  15. Distinctive:

    Test names describe behavior: "returns 404 when user does not exist" not "calls db.findFirst and throws TRPCError".

    line 75
  16. Distinctive:

    No obvious comments. Comment WHY, never WHAT.

    line 88
  17. Distinctive:

    No try/catch in business logic

    line 95
  18. Distinctive:

    No barrel files in app directories

    line 97
  19. Distinctive:

    No mocking of internal dependencies in tests

    line 99
  20. Very specific:

    Do not create index.ts barrel files inside apps/ directories.

    line 104
  21. Very specific:

    Do not use any type. Use unknown and narrow.

    line 105
  22. Very specific:

    Do not use require() or CommonJS syntax.

    line 106
  23. Distinctive:

    Do not mock internal dependencies in tests.

    line 107
  24. Distinctive:

    Do not write tests that mirror implementation.

    line 108
  25. Distinctive:

    Do not use try/catch in service/business logic files.

    line 109
  26. Very specific:

    Do not commit .env files or secrets.

    line 110

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Agent Workflow & Project Conventions

You are a software engineer working in this monorepo. Follow the rules below. For app-specific conventions, read the per-app AGENTS.md files — they are hoisted into your context alongside this one.

Per-app context

  • apps/api/AGENTS.md — backend conventions (Hono + tRPC + Drizzle + SQLite; also serves the MCP endpoint and the built web app)
  • apps/web/AGENTS.md — web app conventions (React + Vite + TanStack Router + Tailwind)

Each app's AGENTS.md describes its layout, run/test commands, and framework-specific rules.

Spec-Driven Development

  • Always ask for a spec before implementing a feature.
  • Session 1: Write failing tests from the spec. Do not implement.
  • Session 2: Implement the minimum code to make tests pass.
  • If you see implementation before tests exist, stop and ask for the spec.

Feature Development

  • Always use nx generate @mealforge/project-plugin:feature --name <name> --apps <apps> before writing feature code.
  • Feature names are camelCase identifiers (userProfile, not user-profile).
  • Never create feature directories manually.
  • The feature generator creates the correct file structure, imports, and wiring — including registering the tRPC router in apps/api/src/trpc.ts.

Task Execution

  • Use nx affected to run only what changed.
  • Use nx run <app>:<task> for specific apps.
  • Use nx run-many --target=<task> when you need to run across all apps.

Language & Runtime

TypeScript everywhere, on Node. Not Bun, not Deno. All code is ESM. No CommonJS.

File Naming

  • camelCase for all files: userService.ts, createPost.ts, authMiddleware.ts
  • React components use PascalCase: UserProfile.tsx, DashboardLayout.tsx
  • Test files sit next to what they test: userService.test.ts alongside userService.ts
  • No index.ts barrel files inside apps/ directories. Only at package boundaries (packages/shared/index.ts).

Exports

  • Default exports for React components only.
  • Named exports for everything else: services, utilities, hooks, types, constants.
  • Every exported function has an explicit return type annotation. No exceptions.

Functions

  • function keyword for all top-level and exported functions.
  • Arrow functions for callbacks, inline handlers, and short expressions only.

Error Handling

  • Services throw TRPCError with the appropriate code.
  • No try/catch blocks in business logic. Ever. The only try/catch blocks are at entry points: the MCP tool handlers, background task runners, top-level process error handlers.

Validation

  • Zod everywhere. Every external input is validated. tRPC procedure inputs and MCP tool inputs use Zod schemas.
  • Shared schemas live in packages/shared/. Feature-specific schemas live in the feature's types.ts.

Testing Rules

  • NEVER write tests after implementation in the same session.
  • Always write failing tests first, based on the spec/requirements, before touching implementation.
  • Tests must derive from expected behavior described in task requirements, not from reading the code.
  • Vitest for unit/integration tests; Playwright (in e2e/) runs against the production build.
  • No mocking unless the dependency is external (network calls, third-party APIs).
  • Test names describe behavior: "returns 404 when user does not exist" not "calls db.findFirst and throws TRPCError".

Linting and Formatting

  • Biome handles both linting and formatting. No ESLint. No Prettier. Single quotes. Semicolons: yes. Tab width: 2 spaces. Trailing commas: all. Print width: 100.

Git

  • Conventional commits: feat:, fix:, chore:, docs:, test:, refactor:
  • One logical change per commit.

Comments

  • No obvious comments. Comment WHY, never WHAT.
  • TODO comments include a brief reason: // TODO: handle pagination once we have >100 users

Code Review Checklist

  • Explicit return types on all exported functions
  • External inputs validated with Zod
  • No try/catch in business logic
  • No any types — use unknown and narrow
  • No barrel files in app directories
  • No CommonJS imports
  • No mocking of internal dependencies in tests
  • Conventional commit message

What Not To Do

  • Do not create index.ts barrel files inside apps/ directories.
  • Do not use any type. Use unknown and narrow.
  • Do not use require() or CommonJS syntax.
  • Do not mock internal dependencies in tests. Only mock external network calls.
  • Do not write tests that mirror implementation. Tests come from specs.
  • Do not use try/catch in service/business logic files.
  • Do not commit .env files or secrets.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free