Artemis
AGENTS.md829 starsChanged 3 years agoMITView on GitHub
Read the checked-in skill for the task at hand. Installation is optional for reading these files; see Work with AI for native skill discovery. Read the relevant guideline for a rule-governed change. Keep procedures in the matching skill. When changing a convention, update its skill and supporting documentation in the same change. These are Artemis-specific rules. The linked guidelines give reasons and exceptions; the skills give procedures. - Transactions belong in repositories, not services or controllers. Do not use @Transactional,…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository8 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ci-triageSkill
- client-conventionsSkill
- e2e-pr-checkSkill
- liquibase-migrationSkill
- local-setupSkill
- server-arch-gatesSkill
- write-testsSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
30 rules. About 0 are common, 17 are distinctive, and 13 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈17
Distinctive · estimate
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 5
Read the checked-in skill for the task at hand.
- Distinctive: line 18
Read the relevant guideline for a rule-governed change.
- Distinctive: line 19
When changing a convention, update its skill and supporting documentation in the same change.
- Very specific: line 29
Do not keep EntityManager or EntityManagerFactory fields in production code.
- Very specific: line 31
Do not use FetchType.EAGER for @OneToOne, @OneToMany or @ManyToMany.
- Very specific: line 33
Do not fetch a lazy configuration through its parent entity, even with @EntityGraph or JOIN FETCH.
- Very specific: line 36
Do not add @Lob or Hibernate second-level @Cache.
- Very specific: line 39
Use getExpiringMap(name, ttl) for entries with a lifetime.
- Very specific: line 46
Read and write JSON through records, never through the Jackson tree model (JsonNode, ObjectNode, ArrayNode, readTree, valueToTree, …
- Very specific: line 49
Every websocket destination is a declared topic: a WebsocketTopic with its WebsocketTopicAccess rule, or a WebsocketUserTopic, as a …
- Very specific: line 56
Use signal APIs. @Input, @Output, @ViewChild, @ViewChildren, @ContentChild and @ContentChildren are banned in application and test support …
- Very specific: line 59
Use @if, @for and @switch, not structural directives, and give every @switch a @default.
- Very specific: line 66
Do not call ComponentRef.setInput in production code.
- Distinctive: line 72
Use TUM AET UI and Tailwind.
- Distinctive: line 76
Use semantic colour tokens, not primitive colours, Bootstrap classes or hand-written PrimeNG root classes.
- Very specific: line 81
Remove unreachable code, even when its only user is its own test.
- Distinctive: line 84
Use client and server, not "frontend" or "backend".
- Distinctive: line 85
Use provider for a swappable distributed-data implementation and adapter for its glue.
- Distinctive: line 99
Before starting or stopping local services, identify the environment and who owns it.
- Distinctive: line 107
When writing documentation, follow the documentation guideline.
- Distinctive: line 109
Add documentation and screenshots only when they help users complete a task or understand a decision.
- Distinctive: line 110
Do not document cosmetic layout details merely to satisfy a checklist.
- Distinctive: line 114
Do not commit plans, design specs or scratch notes.
- Very specific: line 121
Do not edit src/main/webapp during an E2E run.
- Distinctive: line 131
Before creating or updating a PR, follow PR readiness.
- Very specific: line 132
Check completed author tasks with [x], leave pending validation unchecked, and remove only inapplicable tasks and empty sections.
- Distinctive: line 135
Use drafts only for unfinished implementations.
- Distinctive: line 141
If metadata permissions or release context are missing, report the gap and request maintainer help.
- Distinctive: line 144
Do not infer the format from squash-merge subjects, which omit the backticks.
- Distinctive: line 145
Commit subjects are concise and imperative, without backticks.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Repository guidelines
Task-specific guidance
Read the checked-in skill for the task at hand. Installation is optional for reading these files; see Work with AI for native skill discovery.
| Task | Guidance |
| Run, write, or debug Playwright E2E tests | e2e-pr-check |
| Diagnose failed, stuck, or missing CI checks | ci-triage |
| Change server Java or investigate an architecture violation | server-arch-gates |
| Change a database schema or fix a failing changeset | liquibase-migration |
| Change Angular application or TUM AET UI code | client-conventions |
| Write or debug JUnit or Vitest tests | write-tests |
| Set up, build, or troubleshoot the local application | local-setup |
Read the relevant guideline for a rule-governed change. Keep procedures in the matching skill. When changing a convention, update its skill and supporting documentation in the same change.
Non-negotiables
These are Artemis-specific rules. The linked guidelines give reasons and exceptions; the skills give procedures.
Server
- Transactions belong in repositories, not services or controllers. Do not use
@Transactional,TransactionTemplateorPlatformTransactionManagerthere. server development - Do not keep
EntityManagerorEntityManagerFactoryfields in production code. Use Spring Data repositories; raw JDBC access is limited tocore.config. server development - Do not use
FetchType.EAGERfor@OneToOne,@OneToManyor@ManyToMany. Explicitly set@OneToOneto LAZY; do not growFIELDS_ALLOWED_TO_FETCH_EAGERLY. database - Do not fetch a lazy configuration through its parent entity, even with
@EntityGraphorJOIN FETCH. A dependent configuration keeps the parent's key; the parent has no inverse@OneToOnefield. Read it through its own repository. database - Do not add
@Lobor Hibernate second-level@Cache. Use Spring caching only with explicit eviction. database · caching - Cross-node state goes through
DistributedDataProvider, never direct Hazelcast or Redis access. UsegetExpiringMap(name, ttl)for entries with a lifetime. distributed data - Specify a locale for Java case conversion, including in tests. Use
Locale.ROOTfor machine values; keepLocale.ENGLISHonly where the same login convention already applies. server development - Jackson 3 uses
tools.jackson; annotations remaincom.fasterxml.jackson.annotation. Inject the configuredJsonMapperin Spring beans; see the REST API guideline for other contexts. - Read and write JSON through records, never through the Jackson tree model (
JsonNode,ObjectNode,ArrayNode,readTree,valueToTree,createObjectNode) in production code, without exceptions. REST API guideline - Every websocket destination is a declared topic: a
WebsocketTopicwith itsWebsocketTopicAccessrule, or aWebsocketUserTopic, as a constant of the module'sweb/<Module>WebsocketTopicsclass. Send only throughWebsocketMessagingServicewithTOPIC.at(...). Clients send only to/app/...@MessageMappinghandlers, which check the sender; no@SubscribeMapping. websocket
Client
- Use signal APIs.
@Input,@Output,@ViewChild,@ViewChildren,@ContentChildand@ContentChildrenare banned in application and test support code;ngOnChangesis banned. client development - Use
@if,@forand@switch, not structural directives, and give every@switcha@default. Bind styles with[style], not[ngStyle]. client development - Declare root services with
@Service(), not@Injectable({ providedIn: 'root' }), and declareinject()fields before any other member. client development - Route guards return or emit a
UrlTreeorRedirectCommand; resolvers return, emit or throw aRedirectCommand. Never callrouter.navigate()in either, or throw a redirect from a guard.localRules/no-navigation-in-guard-or-resolverbans the navigation calls. client development - Do not call
ComponentRef.setInputin production code; its string input name is not type checked. Declare the components in a template (a@switchfor a closed set) or usesetInputs.localRules/no-component-ref-set-inputbans any use ofsetInput. client development - In production client TypeScript, do not copy objects with spread,
Object.assignorstructuredClone; use the repository's deep-clone helpers. Array spread and object rest are allowed. client development - Use TUM AET UI and Tailwind. Do not add Bootstrap or ng-bootstrap. If TUM AET UI lacks a reusable feature, extend it on native HTML, Angular Aria or stable Angular CDK primitives; use PrimeNG only if that cannot reasonably be done in the same change, and explain the fallback in the PR. TUM AET UI
- Use semantic colour tokens, not primitive colours, Bootstrap classes or hand-written PrimeNG root classes. client theming
Everywhere
- Remove unreachable code, even when its only user is its own test. Required checks run on every
PR:
python3 supporting_scripts/check_dead_code.pyandpnpm run dead-code:client. dead code - Use client and server, not "frontend" or "backend".
<!-- terminology-check: allow -->Use provider for a swappable distributed-data implementation and adapter for its glue. This also applies to commit messages and PR text. terminology
Repository boundaries
- The server uses Spring Boot 4.1 and Java 25; the client uses Angular 22. Use the Gradle wrapper,
Node 24, and the pnpm version pinned in
package.json(corepack enable). Exact versions live ingradle.properties,pnpm-workspace.yaml, andpackage.json. - Server features live under
src/main/java/de/tum/cit/aet/artemis/; the Angular application is undersrc/main/webapp/app/. Keep reusable TUM AET UI components inpackages/tum-aet-ui, with no imports from the Artemis application. Client tests are co-located; server tests are insrc/test/java, Playwright tests insrc/test/playwright. src/main/webapp/app/openapi/is generated client code. Change the API source/generation input rather than hand-editing generated output.- Before starting or stopping local services, identify the environment and who owns it. The E2E runners can kill processes on ports 8080, 9000 and 7921. Reuse a suitable running environment; do not stop unrelated services or run mutating tests against production.
Documentation
- User-facing documentation belongs in
documentation/docs/, grouped by audience. Tool-local READMEs stay beside their tools. Do not create a top-leveldocs/directory. - When writing documentation, follow the documentation guideline. Register new pages in the matching sidebar and link them from related pages.
- Add documentation and screenshots only when they help users complete a task or understand a decision. Do not document cosmetic layout details merely to satisfy a checklist.
- Screenshots in documentation and PRs must be captured from a running Artemis instance with realistic data and the actual theme and background colours. Never use synthetic, AI-generated, mocked or isolated-component screenshots, or override theme colours or recolour a capture. Automated browser capture of the real application is allowed.
- Do not commit plans, design specs or scratch notes. Keep working notes in the issue or PR; maintained documentation belongs on the documentation site.
Testing
- For Playwright locators, use
data-testidfirst; never use styling classes. See E2E testing andwrite-tests. - Do not edit
src/main/webappduring an E2E run; hot reload can invalidate the test. pnpm run vitest:run -- <path>runs the whole suite. Usepnpm exec vitest run <path>for one file. See write-tests for the other test commands.
Commits and pull requests
- Target
develop; rebase to reduce noise. Follow.github/CONTRIBUTING.mdand the guidelines indocumentation/docs/developer/guidelines/. Use.github/PULL_REQUEST_TEMPLATE.md, including the problem and solution, linked issue when applicable, checks run, screenshots for UI changes and documentation updates when relevant. - Before creating or updating a PR, follow PR readiness.
Check completed author tasks with
[x], leave pending validation unchecked, and remove only inapplicable tasks and empty sections. Leave applicable review tasks open until verified. Never claim tests or reviews that were not performed. - Use drafts only for unfinished implementations. Open completed work as non-draft or mark it ready for review immediately so full CI and review bots run. Pending CI, reviews or test-server validation do not require draft status; required checks and applicable reviews must still pass before merge.
- Set the PR milestone to the intended release. Keep draft state and the
ready for review/ready to mergelabels aligned with the documented stage; recheck them after updates. Addready to mergeonly after all remaining tasks, required approvals, resolved threads, passing checks and mergeability are verified. If metadata permissions or release context are missing, report the gap and request maintainer help. - PR titles use a backticked module followed by a colon, e.g.
`Development`: Improve documentation. Allowed modules and the exact pattern are in.github/workflows/validate-pr-title.yml. Do not infer the format from squash-merge subjects, which omit the backticks. - Commit subjects are concise and imperative, without backticks; wrap bodies near 72 characters.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

