Skip to content

draft generic AGENTS.md template #128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
avertrees wants to merge 2 commits into
base: ai-guidelines
Choose a base branch
from
Open

draft generic AGENTS.md template #128

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7a9485b
draft generatic AGENTS.md template
avertrees Jun 22, 2026
6fd9c4c
add contents
avertrees Jun 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions ai-guidelines/templates/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# AGENTS.md

@alea12 alea12 Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we could instruct agents to reference this repo (engineering-general) for general guidelines, with each project being able to add override configurations on top


## Project Overview

[One sentence: language/framework, key versions, what makes this repo architecturally non-standard]

@alea12 alea12 Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Idea: add a prompt that we could use to populate this section using agents. Something like:

You are an expert software developer performing a codebase audit.
Your task: populate the "Project Overview" section of `AGENTS.md`.

Browse the repository and document:
- Primary language(s) and frameworks
- Full tech stack (runtime, build tools, test frameworks, infrastructure, etc.)
- Architectural patterns or notable conventions
- Anything else that would help an agentic model navigate, modify, or extend this codebase effectively

Be specific and concise. Prefer facts over generalities.


## Tech Stack

- Framework: `[ie. Next.js 15 (App Router + Pages Router hybrid)]`
- Language: `[ie. TypeScript]`
- Package Manager: `[ie. pnpm (always use pnpm, never npm)]`

## Key Commands

- Install: `[command]`
- Dev server: `[command]`
- Run all tests: `[command]`
- Run one test: `[command with path/pattern flag]`
- Lint: `[command]`
- Build/compile: `[command]` _(if applicable)_

## Non-Obvious Patterns

### [Pattern name]

[1–3 sentences explaining the mechanism, not just the rule]

## Code Style

- [Convention or constraint]
- [Convention or constraint]

## Testing Rules

- Write tests for all new functionality.
- [Mocking/stubbing convention for this repo]
- [External service strategy: VCR cassettes / webmock / pytest-httpretty / MSW / etc.]
- Run `[test command]` before marking any task complete.
- Tests must be deterministic and isolated — no order-dependent state.

## Boundaries

### Always fine

- Read files and list directory contents
- Run lint, typecheck, and single test files
- Add or edit tests

### Ask first

- Install or remove dependencies (Gemfile, package.json, requirements.txt)
- Delete files
- Make schema or migration changes
- Open PRs or push to any branch

### Never

@entcheva entcheva Aug 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How does this guidance intersect with guidance to prefer deterministic controls for sensitive actions & info? Is this section meant to be additive to that guidance? If so, maybe an opportunity to highlight "and also make sure to..." set up branch protection rules, etc. etc.

https://github.com/NYPL/engineering-general/pull/127/changes#diff-f7315d6c3fe56612eb583769833d4f0d8c173c1a584d9b13608fb47025efaac9R34


- Commit `.env`, secrets, credentials, or API keys
- Force push to `main` or any protected branch
- Modify generated or vendored directories: `vendor/`, `dist/`, `build/`, `node_modules/`, `app/assets/builds/`
- [Any repo-specific protected paths — e.g., Solr config, IIIF schema files]

## Project Structure

- `[path]` — [why it's worth calling out]
- `[path]` — [why it's worth calling out]