Skip to content

A local-first personal finance app

[AI] Establish AI agent commit and PR guidelines (#7153)

Matiss Janis Aboltins73fa068fe978
diff --git a/.cursor/rules/pr-and-commit.mdc b/.cursor/rules/pr-and-commit.mdc
new file mode 100644
index 0000000000..27a906a0b0
--- /dev/null
+++ b/.cursor/rules/pr-and-commit.mdc
@@ -0,0 +1,74 @@
+---
+description: Rules for AI-generated commits and pull requests
+globs:
+alwaysApply: true
+---
+
+# PR and Commit Rules for AI Agents
+
+Canonical source: `.github/agents/pr-and-commit-rules.md`
+
+## Commit Rules
+
+### [AI] Prefix Requirement
+
+**ALL commit messages MUST be prefixed with `[AI]`.** This is a mandatory requirement with no exceptions.
+
+**Examples:**
+
+- `[AI] Fix type error in account validation`
+- `[AI] Add support for new transaction categories`
+- `Fix type error in account validation` (MISSING PREFIX - NOT ALLOWED)
+- `Add support for new transaction categories` (MISSING PREFIX - NOT ALLOWED)
+
+### Git Safety Rules
+
+- **Never** update git config
+- **Never** run destructive git operations (force push, hard reset) unless the user explicitly requests it
+- **Never** skip hooks (`--no-verify`, `--no-gpg-sign`)
+- **Never** force push to `main`/`master`
+- **Never** commit unless explicitly asked by the user
+
+## Pre-Commit Quality Checklist
+
+Before committing, ensure all of the following:
+
+- [ ] Commit message is prefixed with `[AI]`
+- [ ] `yarn typecheck` passes
+- [ ] `yarn lint:fix` has been run
+- [ ] Relevant tests pass
+- [ ] User-facing strings are translated
+- [ ] Code style conventions followed (see `AGENTS.md` for full style guide)
+
+## Pull Request Rules
+
+### [AI] Prefix Requirement
+
+**ALL pull request titles MUST be prefixed with `[AI]`.** This is a mandatory requirement with no exceptions.
+
+**Examples:**
+
+- `[AI] Fix type error in account validation`
+- `[AI] Add support for new transaction categories`
+- `Fix type error in account validation` (MISSING PREFIX - NOT ALLOWED)
+
+### Labels
+
+Add the **"AI generated"** label to all AI-created pull requests.
+
+### PR Template: Do Not Fill In
+
+- **NEVER fill in the PR template** (`.github/PULL_REQUEST_TEMPLATE.md`). Leave all blank spaces and placeholder comments as-is.
+- **Exception**: If a human **explicitly asks** you to fill out the PR template, then fill it out **in Chinese** (简体中文).
+
+## Quick-Reference Workflow
+
+1. Make your changes
+2. Run `yarn typecheck` — fix any errors
+3. Run `yarn lint:fix` — fix any remaining lint errors
+4. Run relevant tests (`yarn test` for all, or workspace-specific)
+5. Stage files and commit with `[AI]` prefix — do not skip hooks
+6. When creating a PR:
+ - Use `[AI]` prefix in the title
+ - Add the `"AI generated"` label
+ - Leave the PR template blank (do not fill it in)
diff --git a/.github/agents/pr-and-commit-rules.md b/.github/agents/pr-and-commit-rules.md
new file mode 100644
index 0000000000..6c4ea50d31
--- /dev/null
+++ b/.github/agents/pr-and-commit-rules.md
@@ -0,0 +1,70 @@
+# PR and Commit Rules for AI Agents
+
+This is the single source of truth for all commit and pull request rules that AI agents must follow when working with Actual Budget.
+
+## Commit Rules
+
+### [AI] Prefix Requirement
+
+**ALL commit messages MUST be prefixed with `[AI]`.** This is a mandatory requirement with no exceptions.
+
+**Examples:**
+
+- `[AI] Fix type error in account validation`
+- `[AI] Add support for new transaction categories`
+- `Fix type error in account validation` (MISSING PREFIX - NOT ALLOWED)
+- `Add support for new transaction categories` (MISSING PREFIX - NOT ALLOWED)
+
+### Git Safety Rules
+
+- **Never** update git config
+- **Never** run destructive git operations (force push, hard reset) unless the user explicitly requests it
+- **Never** skip hooks (`--no-verify`, `--no-gpg-sign`)
+- **Never** force push to `main`/`master`
+- **Never** commit unless explicitly asked by the user
+
+## Pre-Commit Quality Checklist
+
+Before committing, ensure all of the following:
+
+- [ ] Commit message is prefixed with `[AI]`
+- [ ] `yarn typecheck` passes
+- [ ] `yarn lint:fix` has been run
+- [ ] Relevant tests pass
+- [ ] User-facing strings are translated
+- [ ] Code style conventions followed (see `AGENTS.md` for full style guide)
+
+## Pull Request Rules
+
+### [AI] Prefix Requirement
+
+**ALL pull request titles MUST be prefixed with `[AI]`.** This is a mandatory requirement with no exceptions.
+
+**Examples:**
+
+- `[AI] Fix type error in account validation`
+- `[AI] Add support for new transaction categories`
+- `Fix type error in account validation` (MISSING PREFIX - NOT ALLOWED)
+
+### Labels
+
+Add the **"AI generated"** label to all AI-created pull requests. This helps maintainers understand the nature of the contribution.
+
+### PR Template: Do Not Fill In
+
+- **NEVER fill in the PR template** (`.github/PULL_REQUEST_TEMPLATE.md`). Leave all blank spaces and placeholder comments as-is. Humans are expected to fill in the Description, Related issue(s), Testing, and Checklist sections.
+- **Exception**: If a human **explicitly asks** you to fill out the PR template, then fill it out **in Chinese**, using Chinese characters (简体中文) for all content you add.
+
+## Quick-Reference Workflow
+
+Follow these steps when committing and creating PRs:
+
+1. Make your changes
+2. Run `yarn typecheck` — fix any errors
+3. Run `yarn lint:fix` — fix any remaining lint errors
+4. Run relevant tests (`yarn test` for all, or workspace-specific)
+5. Stage files and commit with `[AI]` prefix — do not skip hooks
+6. When creating a PR:
+ - Use `[AI]` prefix in the title
+ - Add the `"AI generated"` label
+ - Leave the PR template blank (do not fill it in)
diff --git a/AGENTS.md b/AGENTS.md
index 3bfa8ef9fe..38b67cbfa1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -44,25 +44,9 @@ yarn start:desktop
### ⚠️ CRITICAL REQUIREMENT: AI-Generated Commit Messages and PR Titles
-**THIS IS A MANDATORY REQUIREMENT THAT MUST BE FOLLOWED WITHOUT EXCEPTION:**
+**ALL commit messages and PR titles MUST be prefixed with `[AI]`.** No exceptions.
-- **ALL commit messages MUST be prefixed with `[AI]`**
-- **ALL pull request titles MUST be prefixed with `[AI]`**
-
-**Examples:**
-
-- ✅ `[AI] Fix type error in account validation`
-- ✅ `[AI] Add support for new transaction categories`
-- ❌ `Fix type error in account validation` (MISSING PREFIX - NOT ALLOWED)
-- ❌ `Add support for new transaction categories` (MISSING PREFIX - NOT ALLOWED)
-
-**This requirement applies to:**
-
-- Every single commit message created by AI agents
-- Every single pull request title created by AI agents
-- No exceptions are permitted
-
-**This is a hard requirement that agents MUST follow. Failure to include the `[AI]` prefix is a violation of these instructions.**
+See [PR and Commit Rules](.github/agents/pr-and-commit-rules.md) for the full specification, including git safety rules, pre-commit checklist, and PR workflow.
### Task Orchestration with Lage
@@ -361,13 +345,7 @@ Always maintain newlines between import groups.
**Git Commands:**
-- **MANDATORY: ALL commit messages MUST be prefixed with `[AI]`** - This is a hard requirement with no exceptions
-- **MANDATORY: ALL pull request titles MUST be prefixed with `[AI]`** - This is a hard requirement with no exceptions
-- Never update git config
-- Never run destructive git operations (force push, hard reset) unless explicitly requested
-- Never skip hooks (--no-verify, --no-gpg-sign)
-- Never force push to main/master
-- Never commit unless explicitly asked
+See [PR and Commit Rules](.github/agents/pr-and-commit-rules.md) for complete git safety rules, commit message requirements, and PR workflow.
## File Structure Patterns
@@ -566,7 +544,7 @@ Icons in `packages/component-library/src/icons/` are auto-generated. Don't manua
Before committing changes, ensure:
-- [ ] **MANDATORY: Commit message is prefixed with `[AI]`** - This is a hard requirement with no exceptions
+- [ ] Commit and PR rules followed (see [PR and Commit Rules](.github/agents/pr-and-commit-rules.md))
- [ ] `yarn typecheck` passes
- [ ] `yarn lint:fix` has been run
- [ ] Relevant tests pass
@@ -579,17 +557,7 @@ Before committing changes, ensure:
## Pull Request Guidelines
-When creating pull requests:
-
-- **MANDATORY PREFIX REQUIREMENT**: **ALL pull request titles MUST be prefixed with `[AI]`** - This is a hard requirement that MUST be followed without exception
- - ✅ Correct: `[AI] Fix type error in account validation`
- - ❌ Incorrect: `Fix type error in account validation` (MISSING PREFIX - NOT ALLOWED)
-- **AI-Generated PRs**: If you create a PR using AI assistance, add the **"AI generated"** label to the pull request. This helps maintainers understand the nature of the contribution.
-
-### PR Template: Do Not Fill In
-
-- **NEVER fill in the PR template** (`.github/PULL_REQUEST_TEMPLATE.md`). Leave all blank spaces and placeholder comments as-is. We expect **humans** to fill in the Description, Related issue(s), Testing, and Checklist sections.
-- **Exception**: If a human **explicitly asks** you to fill out the PR template, then fill it out **in Chinese**, using Chinese characters (简体中文) for all content you add.
+See [PR and Commit Rules](.github/agents/pr-and-commit-rules.md) for complete PR creation rules, including title prefix requirements, labeling, and PR template handling.
## Code Review Guidelines
diff --git a/CLAUDE.md b/CLAUDE.md
index 43c994c2d3..22a20ede81 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1 +1,2 @@
@AGENTS.md
[email protected]/agents/pr-and-commit-rules.md
diff --git a/upcoming-release-notes/7153.md b/upcoming-release-notes/7153.md
new file mode 100644
index 0000000000..df53e0020a
--- /dev/null
+++ b/upcoming-release-notes/7153.md
@@ -0,0 +1,6 @@
+---
+category: Maintenance
+authors: [MatissJanis]
+---
+
+Establish centralized AI governance documentation for commit and pull request standards.