mcollina/init
Creates, updates, or optimizes an AGENTS.md file for a repository with minimal, high-signal instructions covering non-discoverable coding conventions, tooling quirks, workflow preferences, and project-specific rules that agents cannot infer from reading the codebase. Use when setting up agent instructions or Claude configuration for a new repository, when an existing AGENTS.md is too long, generic, or stale, when agents repeatedly make avoidable mistakes, or when repository workflows have changed and the agent configuration needs pruning. Applies a discoverability filter—omitting anything Claude can learn from README, code, config, or directory structure—and a quality gate to verify each line remains accurate and operationally significant.
85
94%
Does it follow best practices?
Impact
72%
1.14xAverage score across 5 eval scenarios
Passed
No known issues
task.mdevals/scenario-5/
Our agent configuration needs an update — agents keep making avoidable mistakes and we think our AGENTS.md might need some love.
The most concrete pain point: our AI agents keep running npm test when they mean to run unit tests, which pulls in slow integration tests and wastes a lot of time. We've mentioned this in code review a few times but it keeps happening. We need this fixed so it sticks.
Beyond that, we suspect our AGENTS.md is just generally stale. Some of the setup steps might be outdated, and there may be important project conventions that agents aren't aware of because they were never written down anywhere agents would look.
Can you take a look at our current AGENTS.md and bring it up to date? Where there are recurring agent mistakes, prefer solutions that actually prevent the mistake over just adding more instructions. We want a leaner, more accurate document — not a longer one.
Current AGENTS.md:
# Agent Instructions
## Setup
- Clone the repo and run `npm install`
- You need Docker installed and running — use `docker-compose up` to start services
(Note: this was required before we moved to a managed dev DB in early 2025 — may no longer apply)
- Copy `.env.example` to `.env` before starting
## Testing
- Run `npm test` to execute tests
## Code style
- We use ESLint and Prettier for code formatting
- Use TypeScript strict mode
- Prefer functional components in React
- Use async/await over promise chains
## Deployment
- Merges to main trigger automatic deployment
- After deployment completes, manually run `npm run db:migrate:prod` in the production console — this step is not automated.cursorrules:
- This is a Next.js 14 app using the App Router
- Use server components by default, client components only when needed for interactivity
- API routes are in app/api/ — do not create new pages/api/ routes (legacy pattern)
- The `experimental/` directory contains work-in-progress features — do not import from it in stable code
- When writing SQL queries, always use the db client from `lib/db.ts`, never import pg directly.github/copilot-instructions.md:
You are helping with a Next.js e-commerce platform.
Tech stack: Next.js 14, TypeScript, PostgreSQL, Stripe.
When writing components, prefer Tailwind for styling.
Important: After any production deployment, a manual migration step is required — run `npm run db:migrate:prod` in the Heroku console. This is not automated.
For unit tests specifically, use `npm run test:unit` (not `npm test` which runs the full suite including slow integration tests).The output should be an updated AGENTS.md file.