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 and how to review code with the shipped review-code skill. It also covers adding skills of your own and tuning automated code review.

The installer adds the instruction files unless you answer no to its Provide AI agent instructions? prompt. Answering no 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 2-tier documentation pattern that the rest of Vortex uses. Agents get project-level decisions first, then Vortex-level procedures:

• 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, without one, to fetch the guide from the website and cache it there.

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 - allows exactly 1 simple command per Bash call, 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: check 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 only a heading and an @AGENTS.md import. Claude Code reads the full development guide through that import, so 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": []
  }
}

In the Vortex repository itself, the file also turns on vortex, the template's maintenance plugin in .vortex/. 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.

Review code

The review-code skill in .claude/skills/review-code/ reviews a change on your machine before a teammate sees it. It reads the code and reports findings. It doesn't edit files or post to GitHub.

Ask your agent for a review in either of these forms:

• Review my branch reviews the current branch against the default branch. The review includes uncommitted and untracked files.
• Review https://github.com/your-org/your-site/pull/123 reviews a pull request without checking out its branch. The skill reads it with the GitHub CLI, so gh must be installed and signed in.

In Claude Code, you can also run /review-code with the same argument.

The review checks the change against 3 sources, in this order:

1. AGENTS.md, the files in docs/ and any AGENTS.md or CLAUDE.md in a directory the change touches. These record your project's decisions and win over the other 2 sources.
2. .claude/skills/review-code/checklist.md, the team's review checklist. It covers Drupal security, Drupal APIs, caching, configuration and updates, tests and front-end code.
3. General engineering judgment.

For a pull request in another repository, the review uses that repository's rules and skips the checklist.

The review skips anything that ahoy lint or another lint command in AGENTS.md already enforces. It sorts findings into Critical, Important and Minor and points each one at a file and line. It ends with a verdict: Ready to merge, Ready after fixes or Needs work. A merged or closed pull request gets follow-ups and no verdict.

Adapt the review to your team

Edit the file that owns the rule you want to change, then commit it:

To change	Edit
What the review checks	.claude/skills/review-code/checklist.md
A project rule the review enforces	AGENTS.md or the matching file in docs/
The procedure or the report format	.claude/skills/review-code/SKILL.md

For example, to stop the review flagging \Drupal:: calls in a legacy module, record that decision in AGENTS.md. The review reads it on every run and doesn't flag what it allows.

Custom skills

A skill is a reusable instruction set for a repeatable, project-specific task, such as a release checklist or a legacy content import.

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 the skill after your commit is merged into the branch they work on. Git ignores everything else under .claude/, so machine-local Claude state stays out of the repository.

Confirm that git status lists the new skill as untracked. After you commit it, git ls-files .claude/skills lists its SKILL.md.

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. It doesn't use PHPMD.
• Removes extra output - the following parts of a review are off:
  • Sequence diagrams
  • The in-progress fortune message
  • Related issues and pull requests
  • Suggested labels and reviewers
  • The docstring coverage check
  • The docstring and unit test generation offers
• 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 hold a yaml-language-server comment with the CodeRabbit schema. Editors that support the comment validate and autocomplete the settings. The CodeRabbit configuration reference lists every setting.