Rules Files & AGENTS.md

Rules files teach Nexgile Code your project’s conventions once, so you never have to repeat them in a prompt. Their contents are injected into every request the agent makes — in every task, and in every sub-agent a task spawns — under a “USER’S CUSTOM INSTRUCTIONS” section of the system prompt. A good rules file is the highest-leverage customization in Nx IDE: five minutes of writing pays off on every task afterward.

The quickest start: .nexgilerules

Create a file named .nexgilerules at your project root. Plain text or Markdown — whatever you write is delivered to the agent verbatim:

# Project Rules

## Stack
- TypeScript strict mode; never use `any` — use `unknown` and narrow.
- React function components only; hooks in src/hooks/, one hook per file.

## Conventions
- All API calls go through src/lib/apiClient.ts — never call fetch directly.
- Components in PascalCase.tsx; hooks as useCamelCase.ts.
- Errors: throw AppError from src/lib/errors.ts, never raw Error.

## Testing
- Vitest. Test files live next to the source file as *.test.ts.
- Run a single test file: pnpm vitest run src/path/file.test.ts

## Never
- Never edit files under src/generated/ — they are code-generated.
- Never add a dependency without asking first.

Commit it. The whole team — and every agent task — now works from the same playbook.

Mode-specific rules: .nexgilerules-<mode-slug>

You often want different guidance for different kinds of work. Add a file named .nexgilerules-<mode-slug> at the project root and it is loaded only when that mode is active, alongside the generic rules:

• .nexgilerules-code — implementation conventions
• .nexgilerules-debug — where the logs are, how to reproduce issues
• .nexgilerules-architect — design constraints, ADR locations
• .nexgilerules-docs-writer — rules for a custom mode you defined

Caution

The suffix must exactly match the mode’s slug — .nexgilerules-code, not .nexgilerules-Code or .nexgilerules-coding. A mismatched name is silently ignored. Check the slug in the mode dropdown or in your .nexgilemodes file.

Directory form: .nexgile/rules/ and .nexgile/rules-<mode-slug>/

When rules outgrow one file, switch to directories. Nexgile Code reads every text file inside:

your-project/
├── .nexgile/
│   ├── rules/                  # generic rules, every mode
│   │   ├── 01-conventions.md
│   │   ├── 02-testing.md
│   │   └── backend/api.md      # nested folders are included too
│   └── rules-code/             # only when Code mode is active
│       └── implementation.md

Details that matter:

• Files are concatenated in alphabetical order by filename — prefix with 01-, 02- to control ordering.
• Nested subfolders and symlinks are followed; each file’s content is labeled with its path.
• Housekeeping files (*.log, *.tmp, *.lock, *.bak, .DS_Store, and similar) are skipped automatically.
• The directory form takes over completely: if any .nexgile/rules/ directory (project or global) contains files, the single .nexgilerules file is not loaded. The same applies per mode — .nexgile/rules-code/ with content means .nexgilerules-code is skipped. Pick one form and stick with it.

Global rules: ~/.nexgile/

Everything above has a global equivalent in your home directory that applies to every project you open:

Scope	Generic rules	Mode-specific rules
Global (all projects)	~/.nexgile/rules/	~/.nexgile/rules-<mode-slug>/
Project	.nexgile/rules/ (or .nexgilerules)	.nexgile/rules-<mode-slug>/ (or .nexgilerules-<mode-slug>)

Global rules load first, then project rules — so project rules appear later in the prompt and naturally refine or override the global baseline. Keep personal universals global (“always answer concisely”, “prefer pnpm”); keep anything project-specific in the repo.

AGENTS.md, AGENT.md, and AGENTS.local.md

Nexgile Code also honors the cross-tool agent-rules convention. If your project root contains:

• AGENTS.md — the standard agent-facing project guide (checked first), or
• AGENT.md — accepted as an alternative spelling (used only when AGENTS.md is absent), plus
• AGENTS.local.md — personal overrides layered on top; keep this one out of version control

their contents are included with your rules on every request. This is controlled by the setting nexgile-code.useAgentRules (default on) in your editor settings; turn it off if you want only .nexgilerules-family files to load.

Generate AGENTS.md with /init

Type /init in the chat input and Nexgile Code analyzes your codebase and writes AGENTS.md for you. It targets roughly 20 concise lines of strictly non-obvious facts: build/lint/test commands (especially how to run a single test), conventions a linter doesn’t enforce, custom utilities that replace standard approaches, and gotchas discovered by actually reading your files. It also writes mode-specific starters under .nexgile/rules-code/, .nexgile/rules-debug/, .nexgile/rules-ask/, and .nexgile/rules-architect/, and it folds in any existing assistant rules it finds (CLAUDE.md, .cursorrules, .cursor/rules/, .github/copilot-instructions.md). Re-running /init on an existing AGENTS.md prunes the obvious and keeps it tight — the file should get shorter, not longer. See Slash Commands for how commands work.

Monorepo subfolder rules

In a monorepo, each package can carry its own rules in a nested .nexgile/ directory:

monorepo/
├── .nexgile/rules/            # repo-wide rules
├── AGENTS.md                  # repo-wide agent guide
├── packages/
│   ├── api/
│   │   ├── .nexgile/rules/    # api-specific rules
│   │   └── AGENTS.md          # api-specific agent guide
│   └── web/
│       └── .nexgile/rules-code/

This is off by default. Enable it with the Enable subfolder rules toggle in Settings → Context (setting enableSubfolderRules). When on, Nexgile Code discovers every nested .nexgile/ directory (skipping node_modules/ and .git/) and loads rules in order: global → project root → subfolders alphabetically. AGENTS.md files in those subfolders are loaded too, each labeled with its path.

Precedence and layering

When a task starts, the custom-instructions section is assembled in this order (later sections sit closer to the task, earlier ones set the baseline):

1. Language preference (if you set one)
2. Global custom instructions (from the Prompts settings)
3. Mode-specific instructions (from the mode’s definition)
4. Mode-specific rules — .nexgile/rules-<slug>/ directories (global, then project, then subfolders if enabled), or the .nexgilerules-<slug> file as fallback
5. .nexgileignore notice (what the agent must not access — see .nexgileignore & Protected Files)
6. AGENTS.md / AGENT.md + AGENTS.local.md (if useAgentRules is on)
7. Generic rules — .nexgile/rules/ directories (global, then project, then subfolders), or .nexgilerules as fallback

Two rules of thumb fall out of this: directories beat single files (single files are a fallback only), and global loads before project, so project rules get the last word.

What makes good rules

Rules are conventions, not essays. The agent already knows how to program — tell it only what it could not guess:

• Concrete and checkable. “Use httpClient.get() from src/lib/http.ts, never axios directly” beats “write clean networking code”.
• Non-obvious only. Skip “write tests” and framework defaults; include “integration tests need docker compose up db first”.
• Short. Keep the total under ~500 words. Rules ride along on every single request — a bloated file costs tokens on every task and dilutes the signal. If it’s growing, move reference material into a skill that loads on demand.
• Include the “never” list. Generated directories, forbidden dependencies, files that must not be touched.
• Maintained. Prune rules that no longer apply; wrong rules are worse than none. Spec Sync can help keep docs current.

Tip

To confirm rules are loading, start a task and ask: “List the project rules you’ve been given, verbatim headers only.” The agent will echo the sections it received.

Related

• Slash Commands — /init and your own reusable prompts
• Custom Modes — personas that pair with .nexgilerules-<slug> files
• Skills — on-demand instruction packages for task-shaped knowledge
• .nexgileignore & Protected Files — rules files are write-protected
• Files & Directories reference — every special file in one table