agentleFS
ls1intumls1intum/Artemis/AGENTS.md

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.

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
  1. Distinctive:

    Read the checked-in skill for the task at hand.

    line 5
  2. Distinctive:

    Read the relevant guideline for a rule-governed change.

    line 18
  3. Distinctive:

    When changing a convention, update its skill and supporting documentation in the same change.

    line 19
  4. Very specific:

    Do not keep EntityManager or EntityManagerFactory fields in production code.

    line 29
  5. Very specific:

    Do not use FetchType.EAGER for @OneToOne, @OneToMany or @ManyToMany.

    line 31
  6. Very specific:

    Do not fetch a lazy configuration through its parent entity, even with @EntityGraph or JOIN FETCH.

    line 33
  7. Very specific:

    Do not add @Lob or Hibernate second-level @Cache.

    line 36
  8. Very specific:

    Use getExpiringMap(name, ttl) for entries with a lifetime.

    line 39
  9. Very specific:

    Read and write JSON through records, never through the Jackson tree model (JsonNode, ObjectNode, ArrayNode, readTree, valueToTree, …

    line 46
  10. Very specific:

    Every websocket destination is a declared topic: a WebsocketTopic with its WebsocketTopicAccess rule, or a WebsocketUserTopic, as a …

    line 49
  11. Very specific:

    Use signal APIs. @Input, @Output, @ViewChild, @ViewChildren, @ContentChild and @ContentChildren are banned in application and test support …

    line 56
  12. Very specific:

    Use @if, @for and @switch, not structural directives, and give every @switch a @default.

    line 59
  13. Very specific:

    Do not call ComponentRef.setInput in production code.

    line 66
  14. Distinctive:

    Use TUM AET UI and Tailwind.

    line 72
  15. Distinctive:

    Use semantic colour tokens, not primitive colours, Bootstrap classes or hand-written PrimeNG root classes.

    line 76
  16. Very specific:

    Remove unreachable code, even when its only user is its own test.

    line 81
  17. Distinctive:

    Use client and server, not "frontend" or "backend".

    line 84
  18. Distinctive:

    Use provider for a swappable distributed-data implementation and adapter for its glue.

    line 85
  19. Distinctive:

    Before starting or stopping local services, identify the environment and who owns it.

    line 99
  20. Distinctive:

    When writing documentation, follow the documentation guideline.

    line 107
  21. Distinctive:

    Add documentation and screenshots only when they help users complete a task or understand a decision.

    line 109
  22. Distinctive:

    Do not document cosmetic layout details merely to satisfy a checklist.

    line 110
  23. Distinctive:

    Do not commit plans, design specs or scratch notes.

    line 114
  24. Very specific:

    Do not edit src/main/webapp during an E2E run.

    line 121
  25. Distinctive:

    Before creating or updating a PR, follow PR readiness.

    line 131
  26. Very specific:

    Check completed author tasks with [x], leave pending validation unchecked, and remove only inapplicable tasks and empty sections.

    line 132
  27. Distinctive:

    Use drafts only for unfinished implementations.

    line 135
  28. Distinctive:

    If metadata permissions or release context are missing, report the gap and request maintainer help.

    line 141
  29. Distinctive:

    Do not infer the format from squash-merge subjects, which omit the backticks.

    line 144
  30. Distinctive:

    Commit subjects are concise and imperative, without backticks.

    line 145

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.

TaskGuidance
Run, write, or debug Playwright E2E testse2e-pr-check
Diagnose failed, stuck, or missing CI checksci-triage
Change server Java or investigate an architecture violationserver-arch-gates
Change a database schema or fix a failing changesetliquibase-migration
Change Angular application or TUM AET UI codeclient-conventions
Write or debug JUnit or Vitest testswrite-tests
Set up, build, or troubleshoot the local applicationlocal-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, TransactionTemplate or PlatformTransactionManager there. server development
  • Do not keep EntityManager or EntityManagerFactory fields in production code. Use Spring Data repositories; raw JDBC access is limited to core.config. server development
  • Do not use FetchType.EAGER for @OneToOne, @OneToMany or @ManyToMany. Explicitly set @OneToOne to LAZY; do not grow FIELDS_ALLOWED_TO_FETCH_EAGERLY. database
  • Do not fetch a lazy configuration through its parent entity, even with @EntityGraph or JOIN FETCH. A dependent configuration keeps the parent's key; the parent has no inverse @OneToOne field. Read it through its own repository. database
  • Do not add @Lob or 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. Use getExpiringMap(name, ttl) for entries with a lifetime. distributed data
  • Specify a locale for Java case conversion, including in tests. Use Locale.ROOT for machine values; keep Locale.ENGLISH only where the same login convention already applies. server development
  • Jackson 3 uses tools.jackson; annotations remain com.fasterxml.jackson.annotation. Inject the configured JsonMapper in 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 WebsocketTopic with its WebsocketTopicAccess rule, or a WebsocketUserTopic, as a constant of the module's web/<Module>WebsocketTopics class. Send only through WebsocketMessagingService with TOPIC.at(...). Clients send only to /app/... @MessageMapping handlers, which check the sender; no @SubscribeMapping. websocket

Client

  • Use signal APIs. @Input, @Output, @ViewChild, @ViewChildren, @ContentChild and @ContentChildren are banned in application and test support code; ngOnChanges is banned. client development
  • Use @if, @for and @switch, not structural directives, and give every @switch a @default. Bind styles with [style], not [ngStyle]. client development
  • Declare root services with @Service(), not @Injectable({ providedIn: 'root' }), and declare inject() fields before any other member. client development
  • Route guards return or emit a UrlTree or RedirectCommand; resolvers return, emit or throw a RedirectCommand. Never call router.navigate() in either, or throw a redirect from a guard. localRules/no-navigation-in-guard-or-resolver bans the navigation calls. client development
  • Do not call ComponentRef.setInput in production code; its string input name is not type checked. Declare the components in a template (a @switch for a closed set) or use setInputs. localRules/no-component-ref-set-input bans any use of setInput. client development
  • In production client TypeScript, do not copy objects with spread, Object.assign or structuredClone; 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.py and pnpm 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 in gradle.properties, pnpm-workspace.yaml, and package.json.
  • Server features live under src/main/java/de/tum/cit/aet/artemis/; the Angular application is under src/main/webapp/app/. Keep reusable TUM AET UI components in packages/tum-aet-ui, with no imports from the Artemis application. Client tests are co-located; server tests are in src/test/java, Playwright tests in src/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-level docs/ 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-testid first; never use styling classes. See E2E testing and write-tests.
  • Do not edit src/main/webapp during an E2E run; hot reload can invalidate the test.
  • pnpm run vitest:run -- <path> runs the whole suite. Use pnpm 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.md and the guidelines in documentation/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 merge labels aligned with the documented stage; recheck them after updates. Add ready to merge only 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.