docs: Update AGENTS.md#346
Conversation
Completed Working on "Code Review"✅ Review comments were published and final review submitted successfully: COMMENT event, 5 total comments across 1 file. ✅ Workflow completed successfully. |
![overcut-ai[bot]](https://avatars.githubusercontent.com/in/1367736?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of review findings:
- Total by importance: 5 MAJOR
- Affected files: 1 (
AGENTS.md) - Blocking issues: none identified (no critical correctness/security defects)
Key themes observed:
- Overly absolute guidance that may conflict with real monorepo workflows (scope/tooling/Nx-only rules).
- Documentation accuracy drift versus current repository/CI reality (paths and path-ignore behavior).
Recommended next steps:
- Relax absolute rules to allow clearly justified exceptions (with rationale + CI alignment).
- Correct repository path examples to match actual docs structure.
- Reconcile CI behavior documentation with current workflow configuration and intended matching semantics.
| 3. **Keep docs/config aligned with code** when behavior or APIs change: | ||
| - update docs content under `docs/` | ||
| - keep OpenAPI/GraphQL generated assets in sync when required. | ||
| 4. **Limit scope of changes** to the relevant app/lib/docs area. |
There was a problem hiding this comment.
[major]: The rule to limit scope to one area is too absolute for a monorepo where correctness often requires coordinated updates across apps/libs/docs/generated artifacts. Keeping it strict can lead to incomplete or inconsistent submissions.
| - update docs content under `docs/` | ||
| - keep OpenAPI/GraphQL generated assets in sync when required. | ||
| 4. **Limit scope of changes** to the relevant app/lib/docs area. | ||
| 5. **Do not introduce new build tooling conventions** when existing Nx/webpack/rollup patterns already cover the use case. |
There was a problem hiding this comment.
[major]: The prohibition against introducing new build-tooling conventions is too rigid and can block justified migrations or improvements when existing patterns are insufficient.
| - `libs/` | ||
| - `client/`, `common/`, `kafka/`, `types/`, `ui/` | ||
| - `docs/` | ||
| - Mintlify content (`docs/mint.json`, `docs/README.md`, `docs/api-reference/*`) |
There was a problem hiding this comment.
[major]: The documented path docs/api-reference/* is inaccurate for this repository structure and can misdirect contributors.
| 4. Build flow: | ||
| - `npx nx graphql:generate --skip-nx-cache` | ||
| - `npx nx run-many --target=build --all --parallel --maxParallel=3` | ||
|
|
There was a problem hiding this comment.
[major]: The guidance around docs path-ignore behavior is inaccurate/misleading for recursive matching expectations, which can cause drift between documentation and actual CI trigger behavior.
| ## Common Tasks | ||
| ### Run one app locally | ||
| - Server: `npx nx serve server` | ||
| - Console: `npx nx serve console` |
There was a problem hiding this comment.
[major]: An absolute ‘do not bypass Nx’ rule conflicts with repository-standard npm script workflows already documented (e.g., docs tooling), creating contradictory guidance.
1 participant
Summary
This PR updates AGENTS.md with the latest repository structure and patterns.
Changes