Skip to content

Commit 2ab9a1b

Browse files
akoclaude
ako
and
claude
committed
docs: add quickstart, capabilities overview, and AI customization guide (#79)
Three new documentation pages to improve developer onboarding: 1. **5-Minute Quickstart** (tutorial/quickstart.md) First page in the tutorial — install, open project, explore, create entity, create microflow, validate. Copy-paste commands with expected output. Links to next steps. 2. **Capabilities Overview** (reference/capabilities.md) Complete table of everything mxcli can do, organized by use case: Read (explore), Write (create/modify), Analyze (lint/search), Automate (CI/CD). Includes known limitations and version requirements. 3. **Customizing AI Generation** (guides/customizing-ai.md) How to make AI assistants follow team conventions: CLAUDE.md for project rules, custom skills for entity/microflow/page patterns, custom commands for workflows, Starlark linter rules for enforcement. Includes concrete examples for naming conventions, audit fields, and page patterns. Updated SUMMARY.md to include quickstart as first tutorial entry and new Guides section before Appendixes. Addresses #79 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 66760c5 commit 2ab9a1b

File tree

4 files changed

+510
-0
lines changed

4 files changed

+510
-0
lines changed

‎docs-site/src/SUMMARY.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111

1212
# Part I: Tutorial
1313

14+
- [5-Minute Quickstart](tutorial/quickstart.md)
1415
- [Setting Up](tutorial/setup.md)
1516
- [Installation](tutorial/installation.md)
1617
- [Opening Your First Project](tutorial/opening-project.md)
@@ -307,6 +308,13 @@
307308

308309
---
309310

311+
# Guides
312+
313+
- [Capabilities Overview](reference/capabilities.md)
314+
- [Customizing AI Generation](guides/customizing-ai.md)
315+
316+
---
317+
310318
# Part X: Appendixes
311319

312320
- [MDL Quick Reference](appendixes/quick-reference.md)

‎docs-site/src/guides/customizing-ai.md‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
# Customizing AI Generation
2+
3+
How to make AI assistants (Claude Code, OpenCode, Cursor, etc.) generate Mendix code that follows your team's conventions.
4+
5+
## How it works
6+
7+
When you run `mxcli init` in your Mendix project, it creates a `.claude/` folder with **skills** -- markdown files that teach AI assistants how to write MDL for your project. The AI reads these before generating code.
8+
9+
```
10+
your-app/
11+
.claude/
12+
CLAUDE.md # Project-level instructions
13+
skills/
14+
write-microflows.md
15+
create-page.md
16+
generate-domain-model.md
17+
check-syntax.md
18+
...
19+
commands/
20+
mendix/
21+
explore.md
22+
create-entity.md
23+
...
24+
```
25+
26+
## Quick setup
27+
28+
```bash
29+
# Initialize AI context in your project
30+
mxcli init -p your-app.mpr
31+
32+
# This creates .claude/ with skills, commands, and a CLAUDE.md
33+
```
34+
35+
Commit the `.claude/` folder to your repo so all team members get the same AI behavior.
36+
37+
## Customizing CLAUDE.md
38+
39+
The `CLAUDE.md` file is the **top-level instruction file** that AI assistants read first. Add your team's conventions here:
40+
41+
```markdown
42+
# Project Instructions
43+
44+
## Naming Conventions
45+
- Entity names: PascalCase, singular (Customer, not Customers)
46+
- Microflow names: ACT_ prefix for button actions, SUB_ for sub-microflows
47+
- Page names: P_ prefix followed by action and entity (P_Customer_Overview)
48+
- Attribute names: PascalCase (FirstName, not first_name)
49+
50+
## Architecture Rules
51+
- All database queries go through a DAL_ (Data Access Layer) microflow
52+
- Never commit objects inside a loop
53+
- Use sub-microflows for logic blocks over 10 activities
54+
- Every entity must have a Name or Description attribute for display
55+
56+
## Security
57+
- Default: no access. Explicitly grant access for each role.
58+
- Admin role gets full access
59+
- User role gets read-only on reference data
60+
61+
## Module Structure
62+
- Core: domain model, enumerations, constants
63+
- API: REST services, consumed services
64+
- UI: pages, snippets, layouts
65+
- Logic: microflows, nanoflows
66+
```
67+
68+
## Writing custom skills
69+
70+
Skills are markdown files in `.claude/skills/` that provide focused guidance for specific tasks. The AI reads the relevant skill when performing that type of work.
71+
72+
### Example: Company-specific entity skill
73+
74+
Create `.claude/skills/create-entity.md`:
75+
76+
```markdown
77+
# Creating Entities
78+
79+
## Standard attributes
80+
Every persistent entity MUST include:
81+
- CreatedDate: DateTime (set by before-commit microflow)
82+
- ModifiedDate: DateTime (set by before-commit microflow)
83+
- CreatedBy: Association to Administration.Account
84+
- IsDeleted: Boolean DEFAULT false (soft delete pattern)
85+
86+
## Example
87+
CREATE PERSISTENT ENTITY CRM.Customer (
88+
Name: String(200) NOT NULL,
89+
Email: String(200),
90+
Phone: String(50),
91+
IsActive: Boolean DEFAULT true,
92+
-- Standard audit fields (required)
93+
CreatedDate: DateTime,
94+
ModifiedDate: DateTime,
95+
IsDeleted: Boolean DEFAULT false
96+
);
97+
98+
CREATE ASSOCIATION CRM.Customer_CreatedBy
99+
FROM CRM.Customer TO Administration.Account
100+
TYPE Reference
101+
OWNER Default;
102+
103+
## Naming rules
104+
- Singular names: Customer, not Customers
105+
- No abbreviations: InvoiceLine, not InvLine
106+
- Boolean attributes: Is/Has prefix (IsActive, HasAddress)
107+
```
108+
109+
### Example: Microflow naming skill
110+
111+
Create `.claude/skills/microflow-naming.md`:
112+
113+
```markdown
114+
# Microflow Naming Convention
115+
116+
## Prefixes
117+
| Prefix | Use | Example |
118+
|--------|-----|---------|
119+
| ACT_ | Button/page actions | ACT_Customer_Save |
120+
| SUB_ | Sub-microflows (called by others) | SUB_ValidateEmail |
121+
| SCH_ | Scheduled events | SCH_CleanupExpiredSessions |
122+
| DS_ | Data sources for widgets | DS_Customer_GetActive |
123+
| DAL_ | Data access layer | DAL_Customer_FindByEmail |
124+
| VAL_ | Validation rules | VAL_Customer_CheckRequired |
125+
| BCO_ | Before commit | BCO_Customer_SetAuditFields |
126+
| ACO_ | After commit | ACO_Order_SendConfirmation |
127+
| BDE_ | Before delete | BDE_Customer_CheckReferences |
128+
129+
## Parameters
130+
- Always use $ prefix: $Customer, $OrderList
131+
- Entity parameters: use entity name ($Customer, not $Cust)
132+
- List parameters: add List suffix ($CustomerList)
133+
- Primitive parameters: descriptive name ($SearchQuery, $MaxResults)
134+
```
135+
136+
### Example: Page patterns skill
137+
138+
Create `.claude/skills/page-patterns.md`:
139+
140+
```markdown
141+
# Page Patterns
142+
143+
## Standard layouts
144+
- Overview pages: DataGrid2 with search, pagination, new/edit buttons
145+
- Edit pages: Popup layout with form fields and Save/Cancel footer
146+
- Detail pages: Full-width layout with tabs for related data
147+
148+
## Widget standards
149+
- Always set Label on input widgets
150+
- Use COMBOBOX for enums with < 10 values, RADIOBUTTONS for < 5
151+
- DataGrid2 for lists, not ListView (unless card layout needed)
152+
- Always add AlternativeText on IMAGE widgets
153+
154+
## Example overview page
155+
CREATE PAGE CRM.P_Customer_Overview (
156+
Title: 'Customer Overview',
157+
Layout: Atlas_Core.Atlas_Default
158+
) {
159+
LAYOUTGRID lgMain {
160+
ROW row1 {
161+
COLUMN col1 (DesktopWidth: 12) {
162+
DATAGRID2 dgCustomers (
163+
DataSource: DATABASE CRM.Customer
164+
WHERE [IsDeleted = false]
165+
SORT BY Name ASC
166+
) {
167+
...columns...
168+
}
169+
}
170+
}
171+
}
172+
}
173+
```
174+
175+
## Using custom commands
176+
177+
Custom commands in `.claude/commands/` let users invoke common workflows with a slash command. Create `.claude/commands/new-entity.md`:
178+
179+
```markdown
180+
Create a new entity with standard audit fields in module $ARGUMENTS:
181+
182+
1. Create the entity with Name, standard audit fields, and soft delete
183+
2. Create the CreatedBy association
184+
3. Create the BCO_ before-commit microflow that sets audit fields
185+
4. Grant Admin full access, User read access
186+
5. Validate with mxcli check
187+
```
188+
189+
Then invoke with: `/new-entity CRM.Product`
190+
191+
## Enforcing conventions with linting
192+
193+
Custom Starlark linter rules in `.claude/lint-rules/` can automatically check conventions:
194+
195+
```python
196+
# .claude/lint-rules/naming_prefix.star
197+
RULE_ID = "CUSTOM001"
198+
RULE_NAME = "Microflow Naming Prefix"
199+
DESCRIPTION = "Microflows must use standard naming prefixes"
200+
CATEGORY = "convention"
201+
SEVERITY = "warning"
202+
203+
VALID_PREFIXES = ["ACT_", "SUB_", "SCH_", "DS_", "DAL_", "VAL_", "BCO_", "ACO_", "BDE_"]
204+
205+
def check():
206+
violations = []
207+
for mf in microflows():
208+
name = mf.name.split(".")[-1] # Get name without module
209+
has_prefix = False
210+
for prefix in VALID_PREFIXES:
211+
if name.startswith(prefix):
212+
has_prefix = True
213+
break
214+
if not has_prefix:
215+
violations.append(violation(
216+
message="Microflow '{}' does not use a standard prefix ({})".format(
217+
mf.qualified_name, ", ".join(VALID_PREFIXES)),
218+
location=location(module=mf.module_name, document_type="microflow",
219+
document_name=mf.name)
220+
))
221+
return violations
222+
```
223+
224+
Run with:
225+
```bash
226+
mxcli lint -p your-app.mpr
227+
```
228+
229+
## Best practices
230+
231+
1. **Commit `.claude/` to git** -- everyone on the team gets the same AI behavior
232+
2. **Start small** -- add one skill at a time, test it, then add more
233+
3. **Use examples** -- one good example teaches more than paragraphs of rules
234+
4. **Run `mxcli lint`** -- automated enforcement is better than hoping the AI remembers
235+
5. **Update skills when conventions change** -- outdated skills cause inconsistency
236+
6. **Use `mxcli check` after generation** -- always validate AI output before committing

0 commit comments

Comments
 (0)