chore: add an agents.md file that describes llm behavior by Skarlso · Pull Request #1788 · open-component-model/open-component-model

Skarlso · 2026-02-16T15:07:42Z

What this PR does / why we need it

We want all agentic devices to follow a common, agreed upon, pattern when working with this repository. Agents.md is a "kinda agreed upon" standard now-a-days for all llm based generators.

Which issue(s) this PR fixes

matthiasbruns

Working with an LLM is great - but we should think about adding git hooks to validate common things like testing and linting to our workflow as a first safeguard

Skarlso · 2026-02-20T20:46:24Z

Okay, so this is late night, I generated a coding guideline that went through a couple iterations. I'm putting it in here, but it will need to be really really well reviewed.

I will run through a couple iterations as well on it.

Skarlso · 2026-02-20T21:10:53Z

It's difficult to define these, because at some point they are rather examples then idioms. The line becomes blurred.

On-behalf-of: Gergely Brautigam <gergely.brautigam@sap.com> Signed-off-by: Gergely Brautigam <182850+Skarlso@users.noreply.github.com>

fabianburth · 2026-03-04T13:23:45Z

@coderabbitai full review

coderabbitai · 2026-03-04T13:23:56Z

✅ Actions performed

Full review triggered.

coderabbitai · 2026-03-04T13:24:08Z

📝 Walkthrough

Walkthrough

Adds two new documentation guides (Agents Guide agents.md and Coding Patterns docs/coding-patterns.md) and updates the repository wordlist (.github/config/wordlist.txt). No executable code or public API surface is modified. (49 words)

Changes

Cohort / File(s)	Summary
Agents Guide `agents.md`	New top-level Agents Guide outlining repo areas (`bindings/go/`, `cli/`, `kubernetes/controller/`, `website/`), agent operating rules, code-review constraints (e.g., No Cross-Module Pollution), controller performance checklist, global conventions (imports, commits/PR titles, codegen, linting), CI overview, runtime type system pointers, and area-specific notes.
Coding Patterns `docs/coding-patterns.md`	New comprehensive coding patterns doc covering constructor patterns, type/enum styles, interface design, error-handling conventions, context placement, concurrency primitives and cleanup, JSON/serialization strategies, receiver conventions, limited generics usage, runtime.Type/Scheme flow, testing/controller/CLI idioms, logging, and codegen markers.
Repository wordlist `.github/config/wordlist.txt`	Small spell/wordlist edits: added `LLM`, added another `Testcontainers` entry, added `overexplain` and `variadic`, removed duplicate `ux` (so `ux` no longer present); ordering/duplication adjustments only. No functional changes.

Sequence Diagram(s)

(Skipped — documentation/config changes only.)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

feat: unify workflows, remove duplications and update packages for the website #2231 — Overlapping edits to .github/config/wordlist.txt.

Suggested reviewers

morri-son
frewilhelm

Poem

"🐰 I hopped through docs with nibbling cheer,

New guides and patterns now appear,
Rules and rhythms laid in rows,
For controllers, CLIs, and code that grows,
A rabbit's wink: read, then engineer!"

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding an agents.md file to guide LLM/agent behavior in the repository, which aligns with the primary addition in the changeset.
Description check	✅ Passed	The description is directly related to the changeset, explaining the purpose of adding agents.md as a standard pattern for agentic devices and referencing the agents.md convention.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/coding-patterns.md (1)

428-428: Hyphenate compound modifier for readability.

Use “pointer-type constraints” here to improve grammatical clarity.

Proposed fix

-Controller utilities use generics with pointer type constraints for K8s objects:
+Controller utilities use generics with pointer-type constraints for K8s objects:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/coding-patterns.md` at line 428, Replace the phrase "pointer type
constraints" with the hyphenated form "pointer-type constraints" in the sentence
that reads "Controller utilities use generics with pointer type constraints for
K8s objects" (look for that exact sentence/phrase in docs/coding-patterns.md) to
improve readability and grammatical clarity.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@agents.md`:
- Around line 76-82: The fenced code block containing the commit messages is
missing a language tag (causing MD040); update the opening fence (the ``` line
before the lines "type(scope): subject" / "feat(cli):..." etc.) to include a
language identifier such as text (i.e. change the opening ``` to ```text) so the
block becomes a proper fenced code block with a language tag.

---

Nitpick comments:
In `@docs/coding-patterns.md`:
- Line 428: Replace the phrase "pointer type constraints" with the hyphenated
form "pointer-type constraints" in the sentence that reads "Controller utilities
use generics with pointer type constraints for K8s objects" (look for that exact
sentence/phrase in docs/coding-patterns.md) to improve readability and
grammatical clarity.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b4d4ffe8-7bdf-4e30-8c40-5fea1568bd7a

📥 Commits

Reviewing files that changed from the base of the PR and between f305bbd and 3fa22e8.

📒 Files selected for processing (2)

agents.md
docs/coding-patterns.md

Skarlso · 2026-03-04T18:02:52Z

@fabianburth Well, it didn't really find anything 🤔

netlify · 2026-04-17T09:04:10Z

✅ Deploy Preview for ocm-website ready!

Name	Link
🔨 Latest commit	`1a0ec4b`
🔍 Latest deploy log	https://app.netlify.com/projects/ocm-website/deploys/69e8d97a37a16f0008c62d8b
😎 Deploy Preview	https://deploy-preview-1788--ocm-website.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

coderabbitai

🧹 Nitpick comments (1)

.github/config/wordlist.txt (1)
25-26: Remove duplicated wordlist entry (Testcontainers).

Line 26 repeats the exact token already present on Line 25. Keeping a single entry avoids churn and keeps the dictionary deterministic.
Proposed minimal diff
 Testcontainers
-Testcontainers
 TransformationGraphDefinition
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.github/config/wordlist.txt around lines 25 - 26, The wordlist contains a
duplicated token "Testcontainers" on consecutive lines; remove the second
occurrence so only a single "Testcontainers" entry remains in the wordlist
(update the file containing the "Testcontainers" entries to delete the duplicate
line).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @.github/config/wordlist.txt:
- Around line 25-26: The wordlist contains a duplicated token "Testcontainers"
on consecutive lines; remove the second occurrence so only a single
"Testcontainers" entry remains in the wordlist (update the file containing the
"Testcontainers" entries to delete the duplicate line).

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bba6f4c1-8438-4dd9-93ff-1e09f6c4299f

📥 Commits

Reviewing files that changed from the base of the PR and between 3fa22e8 and e053617.

📒 Files selected for processing (2)

.github/config/wordlist.txt
agents.md

✅ Files skipped from review due to trivial changes (1)

agents.md

Skarlso · 2026-04-21T13:41:42Z

I'll go over this and do a bit of cleanup later today. :)

…el into add-agents-md

On-behalf-of: Gergely Brautigam <gergely.brautigam@sap.com> Signed-off-by: Gergely Brautigam <182850+Skarlso@users.noreply.github.com>

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/config/wordlist.txt:
- Around line 25-26: Remove the duplicate consecutive entry "Testcontainers"
from the wordlist so the word appears only once; open the
.github/config/wordlist.txt file and delete the repeated line containing
"Testcontainers" to keep the list clean and non-redundant.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 86e24597-77c7-4d23-99a6-23580dd5b5fc

📥 Commits

Reviewing files that changed from the base of the PR and between e053617 and c592087.

📒 Files selected for processing (3)

.github/config/wordlist.txt
agents.md
docs/coding-patterns.md

✅ Files skipped from review due to trivial changes (2)

docs/coding-patterns.md
agents.md

morri-son

lgtm

Skarlso requested a review from a team as a code owner February 16, 2026 15:07

github-actions Bot added kind/chore chore, maintenance, etc. size/l Large labels Feb 16, 2026