Skip to content

Commit dfe3afe

Browse files
jolelievrejolelievre
authored
Merge pull request #2137 from jolelievre/ai-doc
Document AI assisted development
2 parents f065229 + 94db8e6 commit dfe3afe

File tree

4 files changed

+339
-0
lines changed

4 files changed

+339
-0
lines changed

‎development/ai-assisted-development/_index.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: AI-Assisted Development
3+
menuTitle: "AI-Assisted Development"
4+
weight: 80
5+
chapter: true
6+
---
7+
8+
# AI-Assisted Development
9+
10+
PrestaShop provides built-in context files that help AI coding assistants understand the project's architecture, conventions, and domain rules. These files are committed directly in the repositories and require no manual configuration.
11+
12+
{{% notice info %}}
13+
The full `.ai/` context structure in the core repository is available **starting from PrestaShop 9.2**. The [ps_apiresources](https://github.com/PrestaShop/ps_apiresources) and [hummingbird](https://github.com/PrestaShop/hummingbird) repositories already include their own context files.
14+
{{% /notice %}}
15+
16+
## Why built-in AI context?
17+
18+
PrestaShop is a large, mature codebase with strict architectural rules, legacy boundaries, and domain-specific patterns that AI tools cannot infer on their own. Without explicit guidance, AI assistants tend to:
19+
20+
- Generate code using deprecated ObjectModel patterns instead of CQRS
21+
- Ignore multistore constraints
22+
- Mix architectural layers (e.g., calling the database from a controller)
23+
- Miss project-specific naming conventions
24+
25+
The AI context files solve this by providing a **single source of truth** that all AI tools can consume.
26+
27+
## Agnostic by design
28+
29+
Rather than maintaining separate configuration for each AI tool, PrestaShop uses a centralized approach:
30+
31+
1. **`CONTEXT.md` files** contain all the actual guidance (architecture rules, coding standards, do/don't lists, domain knowledge). They are written in plain Markdown, readable by both humans and AI.
32+
33+
2. **Pointer files** at the repository root redirect each tool to the central context:
34+
35+
| File | Tool |
36+
|------|------|
37+
| `CLAUDE.md` | Claude Code |
38+
| `AGENTS.md` | Generic AI agents |
39+
| `.cursor/rules/prestashop-context.mdc` | Cursor |
40+
| `.github/copilot-instructions.md` | GitHub Copilot |
41+
| `.windsurfrules` | Windsurf |
42+
| `GEMINI.md` | Gemini CLI |
43+
44+
This means context is maintained in one place and all tools automatically stay up to date.
45+
46+
## Supported repositories
47+
48+
| Repository | Context structure | Since |
49+
|-----------|-------------------|-------|
50+
| [PrestaShop/PrestaShop](https://github.com/PrestaShop/PrestaShop) | Full `.ai/` hierarchy with domain and component contexts | 9.2 |
51+
| [PrestaShop/ps_apiresources](https://github.com/PrestaShop/ps_apiresources) | Single `CONTEXT.md` at root with pointer files | Available now |
52+
| [PrestaShop/hummingbird](https://github.com/PrestaShop/hummingbird) | Single `CONTEXT.md` at root with pointer files | Available now |
53+
54+
## Read more
55+
56+
{{% children /%}}

‎development/ai-assisted-development/context-structure.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
title: Context Structure
3+
weight: 10
4+
---
5+
6+
# Context Structure
7+
8+
This page describes the `.ai/` folder structure used in the PrestaShop core repository and the simpler context approach used in smaller repositories.
9+
10+
## Core repository: the `.ai/` folder
11+
12+
The [PrestaShop/PrestaShop](https://github.com/PrestaShop/PrestaShop) repository uses a hierarchical `.ai/` folder as the centralized source of truth for all AI-assisted development context.
13+
14+
### Folder layout
15+
16+
```
17+
.ai/
18+
├── CONTEXT.md # Root context: project-wide architecture and rules
19+
├── STRUCTURE.md # Documents the .ai/ folder conventions
20+
├── GOTCHAS.md # Common pitfalls and tricky patterns
21+
├── MULTISTORE.md # Multistore-specific guidance
22+
├── Domain/
23+
│ ├── Cart/
24+
│ │ └── CONTEXT.md # Cart domain rules and patterns
25+
│ ├── Order/
26+
│ │ └── CONTEXT.md
27+
│ ├── Product/
28+
│ │ └── CONTEXT.md
29+
│ └── ... # 57 domain contexts total
30+
├── Component/
31+
│ ├── CQRS/
32+
│ │ └── CONTEXT.md # CQRS component rules
33+
│ ├── Grid/
34+
│ │ └── CONTEXT.md
35+
│ ├── Form/
36+
│ │ └── CONTEXT.md
37+
│ └── ... # 22 component contexts total
38+
├── skills/ # Reusable AI task templates
39+
│ └── ...
40+
└── generated/ # Pre-generated indexes
41+
├── cqrs.md # CQRS commands and queries index
42+
├── routes.md # Routes index
43+
├── entities.md # Entities index
44+
└── hooks.md # Hooks index
45+
```
46+
47+
### Root CONTEXT.md
48+
49+
The [root `.ai/CONTEXT.md`](https://github.com/PrestaShop/PrestaShop/blob/develop/.ai/CONTEXT.md) is the entry point. It provides:
50+
51+
- Project-wide architecture overview (Core Domain, Adapter, PrestaShopBundle, Legacy layers)
52+
- CQRS pattern conventions
53+
- Global coding standards (strict types, `final` classes by default, no ObjectModel in new code)
54+
- An index of all domain and component contexts
55+
- References to generated index files
56+
57+
### Domain contexts
58+
59+
Each domain context (e.g., [`.ai/Domain/Cart/CONTEXT.md`](https://github.com/PrestaShop/PrestaShop/blob/develop/.ai/Domain/Cart/CONTEXT.md)) provides rules specific to that business domain. They follow a standard template defined in [`.ai/STRUCTURE.md`](https://github.com/PrestaShop/PrestaShop/blob/develop/.ai/STRUCTURE.md):
60+
61+
- **Purpose** -- what this domain covers
62+
- **Architecture overview** -- key classes, services, and their relationships
63+
- **Coding standards** -- domain-specific conventions
64+
- **Do / Don't** -- explicit rules for this domain
65+
- **Testing expectations** -- what tests are required
66+
- **Canonical examples** -- reference files to follow
67+
- **Related skills** -- links to reusable task templates
68+
69+
### Component contexts
70+
71+
Component contexts (e.g., `.ai/Component/CQRS/CONTEXT.md`) follow the same template but describe cross-cutting shared infrastructure like Grid, Forms, Hooks, or CQRS. These are especially important because mistakes in shared components propagate across the entire codebase.
72+
73+
### How pointer files work
74+
75+
Pointer files at the repository root contain no context themselves. They simply redirect the AI tool to the `.ai/` folder. For example, `CLAUDE.md` points to `.ai/CONTEXT.md`, which then references the relevant domain and component contexts.
76+
77+
The navigation flow:
78+
79+
```
80+
AI tool reads pointer file (e.g., CLAUDE.md)
81+
→ Follows reference to .ai/CONTEXT.md
82+
→ Discovers domain context (e.g., .ai/Domain/Cart/CONTEXT.md)
83+
→ Discovers component context (e.g., .ai/Component/CQRS/CONTEXT.md)
84+
```
85+
86+
This means that when a developer works on cart-related code with an AI assistant, the assistant can follow this chain to load the Cart domain rules, CQRS component rules, and any cross-cutting guidance it needs.
87+
88+
## Smaller repositories
89+
90+
The [ps_apiresources](https://github.com/PrestaShop/ps_apiresources) and [hummingbird](https://github.com/PrestaShop/hummingbird) repositories use a simpler flat structure with a single `CONTEXT.md` at the root.
91+
92+
### ps_apiresources
93+
94+
The [`CONTEXT.md`](https://github.com/PrestaShop/ps_apiresources/blob/develop/CONTEXT.md) covers:
95+
96+
- Module purpose (declarative API endpoints using CQRS)
97+
- The 8 operation attributes (CQRSGet, CQRSCreate, CQRSPartialUpdate, CQRSDelete, etc.)
98+
- URI and OAuth2 scope naming conventions
99+
- Property naming rules and field mapping strategies
100+
- Testing expectations with `ApiTestCase`
101+
102+
### hummingbird
103+
104+
The [`CONTEXT.md`](https://github.com/PrestaShop/hummingbird/blob/develop/CONTEXT.md) covers:
105+
106+
- Theme architecture (Smarty, SCSS with BEM, vanilla JS/TypeScript, Vite)
107+
- Strict boundaries (no business logic in themes)
108+
- `data-ps-*` attribute system for DOM bindings
109+
- SCSS layer architecture
110+
- Accessibility baseline
111+
- "Vibe coding rules" (no jQuery, strict TypeScript, TDD, Storybook, BEM)
112+
113+
These repositories also include pointer files (`CLAUDE.md`, `.github/copilot-instructions.md`) that reference the root `CONTEXT.md`.
114+
115+
## Canonical template reference
116+
117+
The canonical template for writing `CONTEXT.md` files is documented in [`.ai/STRUCTURE.md`](https://github.com/PrestaShop/PrestaShop/blob/develop/.ai/STRUCTURE.md) in the core repository. Refer to it when creating new context files for domains, components, or external modules.

‎development/ai-assisted-development/maintaining-context.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: Maintaining Context Files
3+
menuTitle: "Maintaining Context"
4+
weight: 30
5+
---
6+
7+
# Maintaining Context Files
8+
9+
This page is for contributors and maintainers who need to create or update AI context files in PrestaShop repositories.
10+
11+
## When to update context files
12+
13+
You should update a `CONTEXT.md` file when:
14+
15+
- **A new domain is created** -- add a new `.ai/Domain/{DomainName}/CONTEXT.md`
16+
- **A new shared component is introduced** -- add a new `.ai/Component/{ComponentName}/CONTEXT.md`
17+
- **Architectural rules change** -- update the relevant domain or component context
18+
- **New patterns or conventions are established** -- reflect them in the appropriate context file
19+
- **Significant refactoring occurs** -- ensure the context still accurately describes the current state
20+
21+
{{% notice tip %}}
22+
The core repository includes a CI check that warns when code in a domain is modified but the corresponding `CONTEXT.md` was not updated in the same pull request. This serves as a reminder, not a blocker.
23+
{{% /notice %}}
24+
25+
## Template
26+
27+
All `CONTEXT.md` files should follow the template defined in [`.ai/STRUCTURE.md`](https://github.com/PrestaShop/PrestaShop/blob/develop/.ai/STRUCTURE.md). The required sections are:
28+
29+
1. **Purpose** -- one or two sentences describing what this domain or component covers
30+
2. **Architecture overview** -- key classes, services, their relationships, and the layer they belong to
31+
3. **Coding standards** -- conventions specific to this area (beyond the global standards)
32+
4. **Do / Don't** -- explicit rules as bullet lists, easy for both humans and AI to parse
33+
5. **Testing expectations** -- what types of tests are required and what they should cover
34+
6. **Canonical examples** -- paths to reference files that represent the expected patterns
35+
7. **Related skills** -- links to reusable task templates in `.ai/skills/` if applicable
36+
37+
## Writing effective context
38+
39+
### Be specific and actionable
40+
41+
Good context gives clear instructions that an AI can follow without ambiguity:
42+
43+
```markdown
44+
## Do
45+
- Use `CartConstraintException` for validation errors in Cart handlers
46+
- Always dispatch `ActionCartUpdated` hook after modifying cart contents
47+
48+
## Don't
49+
- Do not call `Cart` ObjectModel directly from handlers -- use `CartRepository`
50+
- Do not add business logic in `CartController` -- delegate to CQRS commands
51+
```
52+
53+
### Reference real files
54+
55+
Point to actual files in the codebase as canonical examples. AI assistants can then read these files to understand the expected patterns:
56+
57+
```markdown
58+
## Canonical examples
59+
- Command: `src/Core/Domain/Cart/Command/AddCartRuleToCartCommand.php`
60+
- Handler: `src/Adapter/Cart/CommandHandler/AddCartRuleToCartHandler.php`
61+
- Test: `tests/Integration/Behaviour/Features/Scenario/Cart/add_cart_rule.feature`
62+
```
63+
64+
### Keep context current
65+
66+
Context files that describe outdated patterns are worse than no context at all -- they actively mislead AI assistants into generating incorrect code. When reviewing PRs that change domain or component behavior, check whether the corresponding context file needs updating.
67+
68+
## Anti-patterns to avoid
69+
70+
| Anti-pattern | Why it's harmful |
71+
|-------------|-----------------|
72+
| Duplicating context across pointer files | Creates drift between tools; update one place, forget another |
73+
| Writing tool-specific syntax in CONTEXT.md | Breaks the agnostic approach; CONTEXT.md should be plain Markdown |
74+
| Describing what the code does instead of what the rules are | AI can read the code itself; it needs to know the constraints and conventions |
75+
| Leaving placeholder contexts with no real content | Empty contexts waste the AI's attention budget without adding value |
76+
| Copying the full CONTEXT.md into pointer files | Pointer files should only contain a reference, not the content |
77+
78+
## Adding context to modules and themes
79+
80+
External modules and themes can follow the same pattern. For a simple module or theme, a single `CONTEXT.md` at the root is sufficient (see [ps_apiresources](https://github.com/PrestaShop/ps_apiresources/blob/develop/CONTEXT.md) and [hummingbird](https://github.com/PrestaShop/hummingbird/blob/develop/CONTEXT.md) as examples). For larger modules, consider adopting the full `.ai/` folder structure from the core repository.
81+
82+
To support multiple AI tools, add pointer files at the repository root:
83+
84+
- `CLAUDE.md` -- for Claude Code
85+
- `AGENTS.md` -- for generic AI agents
86+
- `.github/copilot-instructions.md` -- for GitHub Copilot
87+
- `.cursor/rules/{module-name}-context.mdc` -- for Cursor
88+
89+
Each pointer file should contain only a reference to the main `CONTEXT.md`:
90+
91+
```markdown
92+
Read and follow the instructions in CONTEXT.md
93+
```

‎development/ai-assisted-development/using-ai-tools.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: Using AI Tools with PrestaShop
3+
menuTitle: "Using AI Tools"
4+
weight: 20
5+
---
6+
7+
# Using AI Tools with PrestaShop
8+
9+
The AI context files are committed directly in the repositories. **No manual setup or configuration is needed** -- just open the project in your preferred tool and start working.
10+
11+
## Tool-specific notes
12+
13+
### Claude Code
14+
15+
Claude Code automatically reads `CLAUDE.md` at the repository root, which points to `.ai/CONTEXT.md`. The full context hierarchy is available without any action from the developer.
16+
17+
### Cursor
18+
19+
Cursor reads the `.cursor/rules/prestashop-context.mdc` file, which references the `.ai/` context. Rules are loaded automatically when the project is opened.
20+
21+
### GitHub Copilot
22+
23+
GitHub Copilot reads `.github/copilot-instructions.md`, which directs it to the `.ai/` context. This works in both VS Code and JetBrains IDEs with the Copilot extension.
24+
25+
### Windsurf
26+
27+
Windsurf reads `.windsurfrules` at the repository root, which points to the centralized context.
28+
29+
### Gemini CLI
30+
31+
Gemini CLI reads `GEMINI.md` at the repository root.
32+
33+
### Web-based assistants (ChatGPT, Claude.ai, Gemini)
34+
35+
For web-based AI assistants that don't read repository files directly, you can copy the content of `.ai/CONTEXT.md` (and any relevant domain or component context) into the conversation as a system prompt or context message.
36+
37+
## Best practices
38+
39+
### Let the AI read the context
40+
41+
Most tools load the context files automatically. If your tool supports it, avoid overriding or skipping the project context. The guidance it contains reflects decisions validated by the project maintainers.
42+
43+
### Point the AI to the right domain
44+
45+
When working on a specific area, reference the relevant domain or component context. For example, if you're working on cart-related code, mention that the AI should consult `.ai/Domain/Cart/CONTEXT.md`. Most tools handle this automatically based on the files you have open, but an explicit reference helps when the scope is ambiguous.
46+
47+
### Review AI-generated code carefully
48+
49+
The context files significantly improve AI output quality, but they don't eliminate the need for review. Always verify that generated code:
50+
51+
- Follows the CQRS pattern where required
52+
- Does not use deprecated ObjectModel patterns in new code
53+
- Respects multistore constraints when applicable
54+
- Includes appropriate tests
55+
56+
{{% notice warning %}}
57+
AI-generated code submitted as a contribution must meet the same quality standards as any other contribution. See the [contribution guidelines on AI use]({{< relref "/9/contribute/contribution-guidelines#on-ai-use-in-contributions" >}}) for the full policy.
58+
{{% /notice %}}
59+
60+
### Use skills for recurring tasks
61+
62+
The `.ai/skills/` folder in the core repository contains reusable task templates for common operations. These help AI assistants produce consistent output for tasks like adding a new CQRS command, creating a Grid definition, or scaffolding a new domain. Check the available skills before asking the AI to perform a task from scratch.
63+
64+
## For AI agents reading this
65+
66+
If you are an AI coding assistant working on PrestaShop code:
67+
68+
1. Start by reading the `CONTEXT.md` file at the root of the `.ai/` folder (or at the repository root for smaller repos like ps_apiresources and hummingbird).
69+
2. Before modifying code in a specific domain, read the corresponding `.ai/Domain/{DomainName}/CONTEXT.md`.
70+
3. Before modifying shared infrastructure, read the corresponding `.ai/Component/{ComponentName}/CONTEXT.md`.
71+
4. Check `.ai/GOTCHAS.md` and `.ai/MULTISTORE.md` for cross-cutting concerns.
72+
5. Use the generated indexes in `.ai/generated/` to discover existing CQRS commands, routes, entities, and hooks.
73+
6. Check `.ai/skills/` for task templates relevant to your current operation.

0 commit comments

Comments
 (0)