Agents rules | Documentation

Agents rules define how AI assistants, such as coding copilots or IDE-integrated agents, behave when they generate or modify code for Contentful apps. By setting clear rules, you improve reliability, reduce rework, and ensure that generated code follows Contentful best practices.

Why agents rules matter

AI tools can accelerate development, but without clear guidance they can introduce inconsistencies, generate unsupported code, or ignore existing patterns in your repository. Agents rules act as guardrails, helping agents understand your Contentful project context and align outputs with your team’s conventions.

How agents rules work

Define rules in one or more text files. Each agent can have its own rules implementation (for example, Cursor Rules). In this guide, use AGENTS.md, an open format supported by multiple coding agents. Most AI-enabled development tools automatically pick up these rules when they generate or refactor code.

A good rule set includes:

Repository context: Describe the repository structure.
Dos and don’ts: State what agents should and should not do.
Official tooling: Reference Contentful tools (CLI, SDKs, APIs) instead of custom scaffolding. For example, see the App Framework.
Verification: Require validation through tests, reviews, and automated checks.

You can also include rules you want to enforce, such as adding tests or following a specific architectural style.

App-specific rules

If your agent supports nested rule files, place an AGENTS.md file in the repository root, and optionally add another AGENTS.md file inside an app folder to apply rules specific to that app.

Best practices

Use these practices:

Keep instructions concise: Agents perform better with short, explicit rules.
Evolve rules: Update AGENTS.md as your repository grows or your conventions change.
Cross-reference docs: Link to official Contentful documentation to prevent unsupported implementations.

AGENTS.md example file

You can use the following AGENTS.md example as a starting point. Copy it into the root of your repository and adjust it to match your preferences. The example is based on a React application using TypeScript and Vite.

1 # Agents Rules for Contentful Apps
2 
3 You are an AI coding assistant specialized in Contentful Apps built with the Contentful App Framework. When context is missing or ambiguous, state assumptions or ask for clarification.
4 
5 ## 1) Context & Scope
6 
7 - This repo contains multiple **Contentful Apps** built with the **App Framework** (React + TypeScript).
8 - Apps are bundled with **Vite** and tested with **Vitest**.
9 - Apps must follow Contentful design and UX conventions using **Forma 36** components.
10 - Agents must:
11   - Load the **entire repository** into context (not just a single app).
12   - Prefer **reuse** of existing components, hooks, utilities, and patterns.
13   - Respect the repository's **ESLint / Prettier / TypeScript** configuration.
14   - Suggest solutions aligned with **Vite** build tooling (avoid Webpack/CRA assumptions).
15 
16 ---
17 
18 ## 2) Golden Rules (TL;DR)
19 
20 1. **Use React + TypeScript + Vite + Vitest + Forma 36** in all solutions.
21 2. **Use official Contentful SDKs and APIs** and reference documentation when proposing solutions.
22 3. **Inspect `package.json` first** in the workspace and app:
23    - Reuse installed libraries and versions.
24    - Add new dependencies only if required and provide justification.
25 4. **Do not use deprecated APIs** (Contentful, Forma 36, React, Vite, or other libraries).
26 5. **TypeScript strictness**: avoid `any` unless absolutely unavoidable; prefer precise types.
27 6. **Clean Code + SOLID principles**: small units, single responsibility, dependency inversion.
28 7. Prefer **small, incremental changes** with clear scope and checklists. Do not add changes that were not requested.
29 8. When commiting changes to git, create atomic commmits and use **Conventional Commits** (https://www.conventionalcommits.org/en/v1.0.0/).
30 
31 ---
32 
33 ## 3) Official Tooling & Documentation
34 
35 - App Framework & App SDK  
36   https://www.contentful.com/extensibility/app-framework/  
37   https://www.contentful.com/extensibility/app-framework/sdk/
38 - App Actions
39   https://www.contentful.com/extensibility/app-framework/app-actions/
40 - App Functions
41   https://www.contentful.com/extensibility/app-framework/functions/#use-case-app-actions
42 - Forma 36 (Design System & React UI Library)  
43   https://f36.contentful.com/  
44   https://www.contentful.com/extensibility/app-framework/forma-36/
45 - API references (index)  
46   https://www.contentful.com/developers/docs/references/
47   - Content Management API (CMA): https://www.contentful.com/references/content-management-api/overview
48   - Content Delivery API (CDA): https://www.contentful.com/references/content-delivery-api/overview
49   - GraphQL Content API: https://www.contentful.com/references/content-delivery-api/overview
50   - Images API: https://www.contentful.com/references/images-api/overview
51   - Preview API: https://www.contentful.com/references/content-preview-api/overview
52 
53 ---
54 
55 ## 4) Dependencies & Libraries Policy
56 
57 - **Inspect `package.json`** in the target app.
58 - **Reuse** installed libraries and versions.
59 - **Do not introduce** new dependencies unless:
60   - No adequate existing library is available, and
61   - The ROI is clear (maintainability, reliability, performance).
62 - If adding a dependency, provide:
63   - Short justification and rejected alternatives.
64   - License, maintenance, and compatibility check.
65   - Versioning consistent with repo conventions.
66 - **No deprecated APIs** (always check release notes).
67 
68 ---
69 
70 ## 5) TypeScript, Coding Standards & Architecture
71 
72 - Follow standard TypeScript and React coding conventions.
73 - **TypeScript**
74   - Avoid `any`. Use explicit, narrow types (interfaces, unions, generics).
75   - Export types for public interfaces; keep internal types scoped.
76 - **Clean Code + SOLID**
77   - Single Responsibility: each module does one thing.
78   - Open/Closed: extend via composition.
79   - Liskov, Interface Segregation, Dependency Inversion: stable boundaries, injected collaborators.
80   - Clear names, small functions, shallow nesting.
81 - **Error handling & UX**
82   - Fail gracefully with Forma 36 notifications and accessible messages.
83   - Wrap CMA calls in try/catch blocks
84 - **Performance**
85   - Debounce field value change listeners if triggering heavy operations.
86   - Use `useMemo` for expensive field calculations.
87   - Lazy load large lists or field editors when possible.
88   - Batch CMA operations where possible
89 - **Accessibility**
90   - Use Forma 36 components (a11y-ready). Add labels/roles/alt text where required.
91 - **Loading & Empty States**
92   - Use `Note` component for empty states with helpful guidance
93   - Disable UI controls during save operations
94 - **SDK Usage**
95   - Always use `useSDK()` hooks from `@contentful/react-apps-toolkit`
96   - Call `sdk.app.setReady()` after async initialization in Config Screen
97   - Use `useAutoResizer()` for Field, Entry, Sidebar and Dialog locations that need dynamic sizing
98 
99 ---
100 
101 ## 6) UI with Forma 36 (mandatory)
102 
103 - Always use **Forma 36** components, tokens, spacing, and density rules.
104 - Avoid plain HTML and ad-hoc CSS; prefer F36 tokens for styling.
105 - Use Forma 36 icons and layout primitives for consistent spacing and typography.
106 
107 ---
108 
109 ## 7) Folder Organization
110 
111 - All apps must reside in the `/apps` directory.
112 - Each app should be self-contained and avoid cross-app dependencies.
113 
114 ---
115 
116 ## 8) Testing Requirements
117 
118 When adding tests:
119 
120 - Use **Vitest** as the default testing framework.
121 - Use **React Testing Library** for component testing.
122 - What to test:
123   - Cover critical logic paths and edge cases.
124   - Prefer tests that resemble real user scenarios.
125 - Tests must run correctly under Vite + Vitest setup.
126 
127 ---
128 
129 ## 9) Code Suggestions scope
130 
131 - Keep proposed code simple and to the point.
132 - UI matches **Forma 36** guidelines and accessibility requirements.
133 - Confirmed **no deprecated** methods by checking documentation.
134 - Propose to add tests after a code change.
135 
136 After adding or changing code, post a short explanation. Explanation must include:
137 
138 - **Goal** (what changes and why).
139 - **Approach** (high level) + links to the exact SDK/API/F36 docs.
140 - **Scope** (files/areas affected) and **dependencies** (reuse existing; propose new only if necessary).
141 
142 
143 ## 10) Before Responding - Verification Checklist
144 
145 After making code changes, verify:
146 
147 - Code builds successfully (`npm run build` in app directory)
148 - No linter errors (`read_lints` on modified files)
149 - TypeScript types are correct (no `any`, proper imports)
150 - All imports are valid and from correct packages
151 - Forma 36 components used correctly (check component API)
152 - No deprecated Contentful SDK methods used
153 - Changes are consistent with existing code patterns in the repo
154 
155 If any check fails, do not proceed.
156 
157 ## 11) Required Response Structure
158 
159 Only after all checks pass, respond with:
160 **Goal** — what is changing and why
161 **Approach** — high-level solution + links to official docs
162 **Scope** — files affected and dependency usage
163 **Git commit proposal** — Conventional Commit format
164 **Next steps** — tests, docs, or follow-ups (if applicable)

Agent rule examples for testing

The following example shows how testing rules can be defined in a dedicated TESTING_AGENT.md file.

1 # Unit testing rules example
2 
3 ## Testing framework and libraries
4 - Use Vitest as the primary testing framework.
5 - Use TypeScript for all test files.
6 - Use descriptive test names that explain the behavior being tested.
7 - Use React Testing Library.
8 
9 ## Test structure and development patterns
10 - Group related tests using `describe` blocks.
11 - Use `beforeEach` and `afterEach` hooks for setup and cleanup.
12 - Create test data factories for complex objects.
13 - Mock external dependencies using `vi.fn()` and `vi.mock()`.
14 - Follow Arrange-Act-Assert pattern for all tests.
15 - Use the TDD approach: create the suite with all use cases first and then the implementation.
16 
17 ## Mocking guidelines
18 - Mock external API calls and services.
19 - Use `vi.spyOn()` for spying on methods.
20 - Create mock implementations for complex dependencies.
21 
22 ## Test utilities
23 - Create factory functions with sensible defaults.
24 - Allow parameter overrides for specific test cases.
25 - Use TypeScript interfaces for type safety.
26 - Include both valid and invalid test data.
27 
28 # Integration Testing Rules Example
29 
30 ## Test Scope and Boundaries
31 - Test interactions between multiple components or services.
32 - Test data flow across system boundaries.
33 - Test external API integrations and third-party services.
34 
35 ## Integration Test Patterns
36 - Test complete user workflows from start to finish.
37 - Test error handling and rollback scenarios.
38 - Test performance under realistic data loads.
39 - Test concurrent operations and race conditions.
40 - Test system resilience and recovery.