Skip to content

Commit 6389d19

Browse files
daniellerouxdanielleroux
committed
docs: add AGENTS.md for development guidelines and best practices
1 parent e1f6d6e commit 6389d19

1 file changed

Lines changed: 143 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
<!--
2+
SPDX-FileCopyrightText: 2026 Siemens AG
3+
4+
SPDX-License-Identifier: MIT
5+
-->
6+
7+
# AGENTS.md
8+
9+
This guide is for humans and AI agents developing inside the Siemens IX monorepo.
10+
11+
## Agent operating principles
12+
13+
- Act as a senior maintainer: inspect existing patterns before changing code, keep changes scoped, and prefer correctness over speed.
14+
- Change source files, not generated artifacts. If generated output is affected, update the source and run the appropriate build/generation step.
15+
- Preserve unrelated user or maintainer changes in the working tree. Do not revert, reformat, or rewrite files outside the requested scope.
16+
- Use the smallest targeted validation that proves the change, then escalate only when needed.
17+
- Prefer explicit, type-safe fixes over broad fallbacks, silent returns, or catch-all error handling.
18+
- Update tests, documentation, examples, and changesets whenever the user-facing behavior, API, styling, accessibility, or package output changes.
19+
20+
## Source of truth and precedence
21+
22+
Use these resources together (in this order when conflicts appear):
23+
24+
1. `CONTRIBUTING.md`
25+
2. `ARCHITECTURE.md`
26+
3. `.github/copilot-instructions.md`
27+
4. `.github/instructions/*.instructions.md`
28+
29+
## Repository architecture (must-know)
30+
31+
- `packages/core` is the source of truth (Stencil Web Components).
32+
- `packages/react`, `packages/angular`, `packages/vue` are wrapper packages generated from Stencil output targets.
33+
- Do not hand-edit generated proxy files (look for auto-generated comments).
34+
- Theme integrations for third-party libraries live in `packages/aggrid` and `packages/echarts`.
35+
36+
## Environment and package manager
37+
38+
- Use the package manager declared in `package.json`: `pnpm@10.17.0`.
39+
- Use Node.js `22.19.0`; Volta is configured for this version.
40+
- Install dependencies from the repository root with `pnpm install`.
41+
- Do not introduce new package managers, lockfiles, formatters, linters, or test runners.
42+
- Add dependencies only when they are required for the implementation, and keep workspace dependencies as `workspace:*` where applicable.
43+
44+
## Development rules
45+
46+
- Prefer changing `packages/core` first for component behavior, API, styling, accessibility, and docs metadata.
47+
- Keep component structure consistent: `<component>.tsx`, `<component>.scss`, tests in `test/`.
48+
- Use SPDX headers for new source files.
49+
- Use design tokens/CSS custom properties instead of hard-coded theme values.
50+
- Keep accessibility parity across frameworks.
51+
- Reuse existing helpers, utilities, tokens, test fixtures, and component patterns before adding new abstractions.
52+
- Avoid arbitrary waits, global side effects, and behavior changes that are not explicitly required.
53+
- For breaking changes, provide migration guidance and update `BREAKING_CHANGES.md`.
54+
55+
## Package-specific guidance
56+
57+
| Package area | Edit guidance |
58+
| --- | --- |
59+
| `packages/core` | Source of truth for Web Components, styles, accessibility, docs metadata, and generated wrapper input. |
60+
| `packages/react`, `packages/angular`, `packages/vue` | Do not edit generated proxy files. Only edit deliberate hand-written helpers, examples, or package-specific integration code. |
61+
| `packages/aggrid`, `packages/echarts` | Keep integrations aligned with IX design tokens and theme classes. Validate visual/theming impact. |
62+
| `packages/documentation` | Update docs generation logic only when documentation output or example extraction changes. |
63+
| `*-test-app` packages | Use for framework examples, previews, and documentation snippets. Keep examples consumer-realistic. |
64+
65+
## Local workflow
66+
67+
```bash
68+
pnpm install
69+
pnpm storybook
70+
pnpm build
71+
pnpm lint
72+
pnpm test
73+
```
74+
75+
Targeted commands:
76+
77+
- Build single package: `pnpm build --filter @siemens/ix`
78+
- Core component tests (watch): `pnpm --filter @siemens/ix test.ct --watch`
79+
- Run visual regression (after build): `pnpm visual-regression`
80+
- Core unit tests: `pnpm --filter @siemens/ix test.spec`
81+
- Core component tests: `pnpm --filter @siemens/ix test.ct`
82+
- Package lint: `pnpm lint --filter <package-name>`
83+
- Package tests: `pnpm test --filter <package-name>`
84+
85+
## Testing expectations
86+
87+
- Build before tests when compiled artifacts, generated wrappers, styles, or visual/component tests depend on build output.
88+
- Core component tests live at `packages/core/src/components/<component>/test/<component>.ct.ts`.
89+
- Include accessibility coverage (`makeAxeBuilder`) and a basic hydration/render test in component test files.
90+
- For UI/theming changes, run relevant visual regression tests after `pnpm build --filter !documentation`; visual regression requires Docker.
91+
- Add or update unit tests for logic changes, component tests for interaction/accessibility changes, and visual tests for meaningful UI or theme changes.
92+
- Prefer Playwright locators, user-visible assertions, and deterministic waits over implementation-detail selectors and timeouts.
93+
94+
## Documentation and examples
95+
96+
- Update component JSDoc, README/docs content, Storybook stories, or test-app examples when public usage changes.
97+
- Keep docs and examples aligned across Web Components, Angular, React, and Vue when the behavior is framework-visible.
98+
- Do not document generated implementation details as public API.
99+
- Ensure examples use supported imports, current component names, and realistic consumer code.
100+
101+
## Changesets and release impact
102+
103+
- Any user-facing change needs a changeset in `.changeset/`.
104+
- This includes API changes, behavior changes, styling/theming updates, accessibility changes, and meaningful bug fixes.
105+
- If a change is internal-only, state that clearly in PR description/review context.
106+
- For breaking changes, update `BREAKING_CHANGES.md` and provide migration notes.
107+
- Choose affected packages based on what consumers install or observe, not only where source files changed.
108+
- Use `patch` for bug fixes and compatible styling/accessibility fixes, `minor` for new backwards-compatible APIs/features, and `major` for breaking API or behavior changes.
109+
- Keep changeset summaries consumer-focused: describe what changed and why it matters, not internal implementation details.
110+
111+
## PR and commit expectations
112+
113+
- PR title format: `<type>[optional <scope>]: <description>` (for example: `fix(core): correct button color`).
114+
- Link requirement context in PR description/commit message (GitHub issue or `IX-<number>`).
115+
- Explain user-facing impact and implementation details clearly.
116+
- Mention validation performed and any intentionally skipped validation with a reason.
117+
- Call out generated files, migration notes, and release impact when relevant.
118+
119+
## Component-test conventions (core)
120+
121+
- Use `regressionTest` from `@utils/test` (not plain Playwright `test`).
122+
- Use Playwright locators (including for Shadow DOM assertions).
123+
- Avoid arbitrary timeouts (`waitForTimeout`).
124+
- Register icons via mount config; do not fetch static SVG files directly in tests.
125+
126+
## Security and contribution hygiene
127+
128+
- Do not report security issues publicly in GitHub issues; follow `SECURITY.md` / `CONTRIBUTING.md` private reporting path.
129+
- Keep changes scoped and package-aware.
130+
- Do not edit unrelated files while implementing a focused change.
131+
- Never commit secrets, credentials, private tokens, local environment files, or machine-specific paths.
132+
- Treat public APIs, accessibility behavior, theming tokens, and generated package output as consumer contracts.
133+
- Do not add telemetry, network calls, or dependency downloads without a clear project-approved reason.
134+
135+
## Quick execution checklist
136+
137+
1. Confirm target package(s) and whether `core` is the correct edit point.
138+
2. Inspect nearby existing patterns, tests, docs, and package scripts.
139+
3. Implement changes in source (not generated output).
140+
4. Update tests, examples, docs, and generated inputs as needed.
141+
5. Run the smallest meaningful build/test/lint commands; run visual regression for relevant UI/theme changes.
142+
6. Add/update a changeset if the change is user-facing.
143+
7. Ensure PR summary includes impact, linked requirement, validation, affected packages, and migration notes if breaking.

0 commit comments

Comments
 (0)