AI

Vortex ships instructions for AI coding agents, so an agent that works on your project starts with the context a new teammate would get. That covers the commands to run, the rules to follow, and where the documentation lives.

This page is for developers who work on a Vortex project with an AI coding agent such as Claude Code. It explains what each instruction file gives the agent, how to add skills of your own, and how to tune automated code review.

The installer adds the instruction files unless you answer no to its Provide AI agent instructions? prompt. That answer leaves out the following:

• AGENTS.md
• CLAUDE.md
• The .claude/ directory
• The .claude/ rules in .gitignore

How it works

The agent instructions follow the same two-tier documentation pattern that the rest of Vortex uses:

• What applies to the project lives in the docs/ directory. Before an implementation decision, the agent checks the relevant file there for the project's choices, such as testing conventions, CI configuration, deployment rules, and release processes.
• How to perform operations comes from the Vortex documentation, this site. AGENTS.md instructs agents to look for a cached copy in .artifacts/ first, and to fetch the guide from the website and cache it there when there's no copy yet.

AI agents get the same layered guidance as you do: project-level decisions first, then Vortex-level procedures.

Configuration files

AGENTS.md

The AGENTS.md file in the project root is the primary configuration for AI coding agents. It's agent-agnostic, so any AI tool that reads AGENTS.md can use it.

The file has these sections, in order:

• Highest priority rule - limits every Bash call to exactly 1 simple command, with no chaining, pipes, command substitution, or here-documents.
• Daily development tasks - a reference of ahoy commands for building, testing, and managing the local environment.
• Before starting any task - a checklist for the start of every task: the cached documentation in .artifacts/ first, then the project's docs/ files, then the website for anything missing.
• Critical rules - constraints that agents must always follow:
  • Never modify the shipped scripts in vendor/drevops/vortex-tooling/src/.
  • Never run ad-hoc code with ahoy drush php:eval, and never pass it inline: write it to a file first.
  • Always export the configuration after changes in the admin UI.
  • Never use compound Bash commands.
• Key directories - the project's directory layout.
• Documentation - instructions for agents to check docs/ files for project-specific decisions and to fetch operational documentation from the Vortex documentation. Fetched pages are cached in .artifacts/docs-[topic].md with their source URL and date, so agents reuse them across sessions instead of fetching them again.

CLAUDE.md

Claude Code loads the CLAUDE.md file automatically at the start of every session. It holds nothing but a heading and an @AGENTS.md import, so Claude Code reads the full development guide along with it, and there's only 1 set of instructions to maintain.

.claude/settings.json

The .claude/settings.json file is a checked-in Claude Code settings file that pre-approves every ahoy command. An agent can then build, provision, lint, and test through ahoy without asking you to confirm each call:

{
  "permissions": {
    "allow": [
      "Bash(ahoy:*)"
    ],
    "deny": []
  }
}

The copy in the Vortex repository also turns on the vortex plugin, the template's own maintenance plugin in its .vortex/ directory. The installer removes those entries, so your project gets only the permissions block.

Personal, machine-local settings belong in .claude/settings.local.json, which Git ignores.

Custom skills

Skills are reusable instruction sets that teach an agent a repeatable, project-specific task, such as a release checklist or a legacy content import procedure.

Add a skill by creating a SKILL.md file in its own directory under .claude/skills/:

.claude/
└── skills/
    └── import-legacy-content/
        └── SKILL.md

Start SKILL.md with frontmatter that names the skill and says when to use it, then write the instructions:

---
name: import-legacy-content
description: Use when importing legacy content from the CSV exports
---

Instructions the agent follows when the skill is invoked.

The shipped .gitignore un-ignores .claude/skills/ alongside .claude/settings.json, so you commit a skill like any other file. Your teammates get it after you push the commit and it's merged into the branch they work on. Everything else under .claude/ stays ignored, which keeps machine-local Claude state out of the repository.

Confirm that git status lists the new skill as untracked, which shows that Git doesn't ignore it. After you commit it, git ls-files .claude/skills lists its SKILL.md, which shows that Git tracks it.

AI code review

CodeRabbit is an automated reviewer that comments on pull requests. Vortex ships a .coderabbit.yaml file that tunes its reviews to your project. The file needs no credentials or tokens.

The installer adds the file when you answer yes to its Configure AI code review with CodeRabbit? prompt. The default answer is no, because the file has an effect only after you install the CodeRabbit app on your repository.

The configuration makes these changes to the CodeRabbit defaults:

• Reviews against your conventions - CodeRabbit reads AGENTS.md and the Markdown files in docs/ as coding guidelines. The installer drops the docs/ entries when you don't keep the project documentation.
• Limits comments to issues that matter - the chill review profile and the tone instructions restrict comments to correctness, security, performance, and maintainability.
• Leaves linting to your linters - CodeRabbit's own PHPCS, PHPMD, PHPStan, ESLint, and Stylelint runs are off. The project runs PHPCS, PHPStan, ESLint, and Stylelint in CI with its own configuration, and doesn't use PHPMD.
• Removes extra output - sequence diagrams, related issues and pull requests, suggested labels and reviewers, the docstring coverage check, and the docstring and unit test generation offers are off.
• Skips lock files - composer.lock, package-lock.json, and yarn.lock are excluded from review.
• Adds instructions for 2 paths - CodeRabbit reviews exported configuration in config/ only for changes to permissions, content access, and security settings. It reviews Behat features against docs/testing.md.

The copy in the Vortex repository also excludes the installer's test fixtures from review. The installer removes that entry.

Tune the configuration

Edit .coderabbit.yaml and commit it. CodeRabbit applies the committed file to the next review.

The following table lists the settings you're most likely to change:

Setting	Controls
reviews.profile	quiet for the most important issues only, chill for balanced feedback, assertive for more comments
tone_instructions	Free-text guidance for every review, up to 250 characters
reviews.path_instructions	Extra review instructions for files that match a path pattern
reviews.path_filters	Files to review; a pattern that starts with ! excludes files
reviews.tools	The linters and analyzers that CodeRabbit runs itself
knowledge_base.code_guidelines.filePatterns	The guideline files that CodeRabbit reads

To add review instructions for your custom modules, add an entry to the reviews.path_instructions list:

    - path: 'web/modules/custom/**'
      instructions: 'Prefer dependency injection over static service calls.'

The first lines of the file point editors that support the yaml-language-server comment at the CodeRabbit schema. These editors validate and autocomplete the settings. The CodeRabbit configuration reference lists every setting.