Add AGENTS.md with project conventions#874
Conversation
Captures the conventions that have come up repeatedly in PR reviews but weren't written down anywhere (CONTRIBUTING.md only covers code-style basics). Topics include: reusing existing utilities (Timeout, Button, DismissClickOverlay, LiveStreamDetector, …), Player ↔ UI boundary rules (player.exports, source of truth, no defensive try/catch), component design (no Component without DOM, shared state on UIManager, stable subscription refs, prefer derived values, no reparenting), iOS reality check, default-on caution, "Player vs UI" scope questions, anti-patterns (bandaid timers, vague names), CHANGELOG hygiene, and a pre-commit checklist. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a new AGENTS.md at the repository root to document project-specific conventions and review heuristics for bitmovin-player-ui, intended to reduce repeated review feedback and standardize patterns across contributions.
Changes:
- Introduces
AGENTS.mdwith guidance on UI structure boundaries (UIFactory/UIManager), player API usage, component patterns, and verification habits. - Documents mobile SDK considerations (Android/iOS WebView/native-bridge constraints) for UI changes that depend on platform behavior.
- Adds checklists and conventions around PR shape, changelog hygiene, and common anti-patterns.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
stonko1994
changed the title
matamegger
left a comment
matamegger
left a comment
There was a problem hiding this comment.
It's a bit on the longer side. I think it could probably be more concise in it's phrasing.
But most important is that it works when working on the project.
Should we also add a CLAUDE.md symlinking to the AGENTS.md.
AFAIK claude is not automatically injecting AGENTS.md in the context.
|
|
||
| ## Scope | ||
|
|
||
| These notes apply to `bitmovin-player-ui` checkouts and worktrees. Keep the guidance focused on how this UI framework is structured. |
There was a problem hiding this comment.
| These notes apply to `bitmovin-player-ui` checkouts and worktrees. Keep the guidance focused on how this UI framework is structured. |
| - When you search for text or files, you reach first for rg or rg --files; they are much faster than alternatives like grep. If rg is unavailable, you use the next best tool without fuss. | ||
| - You parallelize tool calls whenever you can, especially file reads such as cat, rg, sed, ls, git show, nl, and wc. |
There was a problem hiding this comment.
Is such guidance still needed for commonly used agent harnesses?
I fill like such instructions are not needed on project level, if at all.
| - You may be in a dirty git worktree. | ||
| - While working, you may encounter changes you did not make. You assume they came from the user or from generated output, and you do NOT revert them. If they are unrelated to your task, you ignore them. If they affect your task, you work with them instead of undoing them. Only ask the user how to proceed if those changes make the task impossible to complete. | ||
| - NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user. | ||
| - If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes. | ||
| - If the changes are in files you've touched recently, you should read carefully and understand how you can work with the changes rather than reverting them. | ||
| - If the changes are in unrelated files, just ignore them and don't revert them. |
There was a problem hiding this comment.
Not sure if needed on project level or if that should be part of personal or global agent guidance.
Generally the content seems fine/good.
There was a problem hiding this comment.
I thought the same! My reasoning for adding it was that I still regularly experience this when working, and I thought, why not add it? One regular use case in the UI actually is modifying the index.html for testing.
Description
Adds a repo-level
AGENTS.mdwith concise guidance for working inbitmovin-player-ui.This PR originally started as a longer project-conventions document. After review, the content was narrowed to repo-wide steering rather than component-specific or user-specific workflow notes. The current version focuses on how to work with the UI framework structure and keeps detailed feature documentation out of the agent file.
The guidance now covers:
UIFactory,UIManager,UIInstanceManager, component ownership, lifecycle cleanup, and Shadow DOM/root-sensitive behaviorMobileV3PlayerAPIboundariesThe current structure came from three cleanup passes:
Checklist (for PR submitter and reviewers)
CHANGELOGentry