docs: add AGENTS.md guide for AI agents

[MatissJanis]

This PR adds a comprehensive AGENTS.md file to help AI agents (like Cursor) work effectively with the Actual Budget codebase.

What's included:

• Project Overview: Description of Actual Budget, repository structure, and links
• Quick Start Commands: Essential commands for development, testing, and linting
• Architecture & Package Structure: Detailed breakdown of all 9 packages in the monorepo
• Development Workflow: Best practices for making changes, testing, and type checking
• Code Style & Conventions: TypeScript/React patterns, naming conventions, and forbidden patterns
• File Structure Patterns: Example component and test file structures
• Important Directories & Files: Where to find key files and what to avoid editing
• Common Development Tasks: Recipes for frequent operations
• Troubleshooting: Solutions to common issues (type errors, linter errors, test failures, etc.)
• Testing Patterns: Unit, E2E, and visual regression testing guidelines
• Code Quality Checklist: What to verify before committing
• Pull Request Guidelines: Notes about labeling AI-generated PRs

This guide will be particularly useful for AI coding assistants to understand the project structure, conventions, and best practices without needing to explore the codebase extensively.

[netlify]

✅ Deploy Preview for actualbudget ready!

Name	Link
🔨 Latest commit	be63a0b
🔍 Latest deploy log	https://app.netlify.com/projects/actualbudget/deploys/68f2a900c673730008a09845
😎 Deploy Preview	https://deploy-preview-5942.demo.actualbudget.org
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[youngcw]

Probably should use v24 here

[MatissJanis]

I don't think we're on v24. And judging from the conversations in the node upgrade PR - it might not be upgraded anytime soon.

[MatissJanis]

This is the discussion: #5937 (review)
(forgot to link it before)

[StephenBrown2]

Should this also remove the .cursor/rules, so as to remove any duplication?

[MatissJanis]

Should this also remove the .cursor/rules, so as to remove any duplication?

Good shout!

[coderabbitai]

Walkthrough

This pull request removes three cursor rule documentation files from the .cursor/rules/ directory: commands.mdc, typescript.mdc, and unit-tests.mdc. These files previously contained AI guidance for the Cursor IDE, including Yarn command recommendations, TypeScript/React coding guidelines, and unit testing conventions. The removal eliminates all three static guidance files without introducing new content.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

The changes consist of simple file deletions with no logic modifications. The reviewer only needs to verify that removing these three documentation files is intentional and appropriate for the project.

Possibly related PRs

• TypeScript: convert edit rules modal #5543: Directly related as it modifies the same .cursor/rules/ files that are being removed in this PR, suggesting a potential reversal or cleanup of cursor configuration changes.

Suggested reviewers

• MikesGlitch

Pre-merge checks and finishing touches

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "docs: add AGENTS.md guide for AI agents" clearly and specifically describes the primary objective of this pull request. According to the PR description and objectives, the main purpose is to add a comprehensive AGENTS.md documentation file to help AI agents work effectively with the codebase. While the raw summary also shows removal of three .cursor/rules files, these appear to be complementary changes to consolidate documentation and avoid duplication. The title effectively captures the core intent of adding new documentation without unnecessary verbosity or vagueness.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/add-agents-guide

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 19675a7 and be63a0b.

⛔ Files ignored due to path filters (2)

• AGENTS.md is excluded by !**/*.md
• upcoming-release-notes/5942.md is excluded by !**/*.md

📒 Files selected for processing (3)

• .cursor/rules/commands.mdc (0 hunks)
• .cursor/rules/typescript.mdc (0 hunks)
• .cursor/rules/unit-tests.mdc (0 hunks)

💤 Files with no reviewable changes (3)

• .cursor/rules/commands.mdc
• .cursor/rules/unit-tests.mdc
• .cursor/rules/typescript.mdc

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (9)

• GitHub Check: Functional Desktop App
• GitHub Check: Wait for Netlify build to finish
• GitHub Check: test
• GitHub Check: validate-cli
• GitHub Check: web
• GitHub Check: build (macos-latest)
• GitHub Check: build (ubuntu-22.04)
• GitHub Check: build (windows-latest)
• GitHub Check: Analyze

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[StephenBrown2]

@coderabbitai The instructions were move to AGENTS.md to be more generally applicable to other AI agents than Cursor.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@StephenBrown2: Thank you for the clarification! That makes perfect sense. Moving the instructions from .cursor/rules to AGENTS.md is a great approach to make the guidance accessible and useful for multiple AI coding assistants (like Cursor, Copilot, Aider, etc.) rather than being siloed in Cursor-specific configuration. This consolidation eliminates duplication while broadening the reach of the documentation. 👍

---

✏️ Learnings added

Learnt from: StephenBrown2
URL: https://github.com/actualbudget/actual/pull/5942

Timestamp: 2025-10-17T20:44:04.391Z
Learning: In the Actual Budget repository, AI agent instructions should be placed in AGENTS.md rather than tool-specific directories like .cursor/rules, to make the documentation more generally applicable to various AI agents (Cursor, Copilot, Aider, etc.) rather than being specific to one tool.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.