Improved AGENTS.md documentation structure #25591
Conversation
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the WalkthroughThis change restructures agent-facing documentation across the monorepo. The root Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
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. Comment |
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://cdn.statically.io/img/avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
���� Nitpick comments (4)
agent-docs/analytics.md (1)
1-20: Fix bare URL formatting on line 9.The URL
http://localhost:7181should be wrapped in angle brackets or markdown link syntax to comply with markdown standards.-Access Tinybird UI at http://localhost:7181 when enabled. +Access Tinybird UI at <http://localhost:7181> when enabled.agent-docs/how_to_write_an_agents_md.md (1)
92-127: Add language specifiers to fenced code blocks.Lines 127 and 139 contain fenced code blocks without language identifiers. Add
markdownor an appropriate language identifier after the opening backticks.-``` +```markdown # Bad (in AGENTS.md)agent-docs/react-query.md (1)
1667-1667: Wrap bare URL reference in angle brackets.Line 1667 contains a bare URL to TkDodo's blog. Wrap it for consistency with markdown standards.
-*This comprehensive reference covers all 31 posts from TkDodo's Practical React Query blog series. For deeper dives into specific topics, refer to the original posts at https://tkdodo.eu/blog/practical-react-query* +*This comprehensive reference covers all 31 posts from TkDodo's Practical React Query blog series. For deeper dives into specific topics, refer to the original posts at <https://tkdodo.eu/blog/practical-react-query>*agent-docs/docker-development.md (1)
40-49: Optional: Wrap bare URLs for stricter Markdown compliance.Markdownlint flags bare URLs in the services table (lines 43–49). While these are acceptable Markdown, wrapping them in angle brackets would satisfy stricter linters without affecting readability. This is optional and a low-priority refactor.
Example wrapping:
- | Ghost | http://localhost:2368 | Database: `ghost_dev` | + | Ghost | \`http://localhost:2368\` | Database: `ghost_dev` |
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (11)
AGENTS.md(1 hunks)agent-docs/analytics.md(1 hunks)agent-docs/architecture.md(1 hunks)agent-docs/docker-development.md(1 hunks)agent-docs/how_to_write_an_agents_md.md(1 hunks)agent-docs/react-query.md(1 hunks)agent-docs/testing.md(1 hunks)apps/shade/AGENTS.md(1 hunks)apps/shade/CLAUDE.md(1 hunks)apps/shade/docs/shadcn-workflow.md(1 hunks)e2e/AGENTS.md(1 hunks)
��� Additional context used
🧠 Learnings (60)
📓 Common learnings
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: e2e/CLAUDE.md:0-0
Timestamp: 2025-11-24T17:28:42.084Z
Learning: AGENTS.md - Documentation file for agent specifications and guidelines
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T17:28:38.037Z
Learning: Reference agents must define the agent's purpose, capabilities, and expected inputs/outputs in documentation
📚 Learning: 2025-11-24T17:28:42.084Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: e2e/CLAUDE.md:0-0
Timestamp: 2025-11-24T17:28:42.084Z
Learning: AGENTS.md - Documentation file for agent specifications and guidelines
Applied to files:
agent-docs/testing.mdapps/shade/CLAUDE.mde2e/AGENTS.mdAGENTS.mdapps/shade/AGENTS.mdagent-docs/how_to_write_an_agents_md.md
📚 Learning: 2025-11-24T17:29:43.865Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: e2e/AGENTS.md:0-0
Timestamp: 2025-11-24T17:29:43.865Z
Learning: Always refer to `.claude/E2E_TEST_WRITING_GUIDE.md` for comprehensive testing guidelines and patterns when creating or modifying E2E tests
Applied to files:
agent-docs/testing.mdagent-docs/how_to_write_an_agents_md.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Check `e2e/CLAUDE.md` for detailed E2E testing guidance and debugging tips
Applied to files:
agent-docs/testing.mdagent-docs/how_to_write_an_agents_md.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Run `yarn test:integration` for integration tests in ghost/core
Applied to files:
agent-docs/testing.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Run `yarn test:unit` for unit tests in all packages or `yarn test:single` for individual test files
Applied to files:
agent-docs/testing.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Applies to e2e/**/*.{ts,js} : E2E tests should use Playwright with Docker container isolation
Applied to files:
agent-docs/testing.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Run `yarn lint` to lint all packages or `cd ghost/core && yarn lint` to lint Ghost core (server, shared, frontend, tests)
Applied to files:
agent-docs/testing.md
📚 Learning: 2025-11-24T17:29:43.865Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: e2e/AGENTS.md:0-0
Timestamp: 2025-11-24T17:29:43.865Z
Learning: Applies to e2e/**/*.test.ts : Test suite names should follow the format 'Ghost Admin - Feature' or 'Ghost Public - Feature'
Applied to files:
agent-docs/testing.md
📚 Learning: 2025-11-26T11:05:59.314Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/shade/AGENTS.md:0-0
Timestamp: 2025-11-26T11:05:59.314Z
Learning: Applies to apps/shade/test/unit/**/*.test.{ts,tsx,js} : Vitest unit tests should be located in `test/unit/*` with pattern `test/unit/**/*.(test).(ts|tsx|js)` and use the `render` helper from `test/unit/utils/test-utils.tsx`
Applied to files:
agent-docs/testing.md
📚 Learning: 2025-11-24T17:29:43.865Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: e2e/AGENTS.md:0-0
Timestamp: 2025-11-24T17:29:43.865Z
Learning: Applies to e2e/**/*.test.ts : Use Playwright's auto-waiting capabilities and run tests multiple times to ensure stability
Applied to files:
agent-docs/testing.mde2e/AGENTS.md
📚 Learning: 2025-11-24T17:29:43.865Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: e2e/AGENTS.md:0-0
Timestamp: 2025-11-24T17:29:43.865Z
Learning: Each test receives fresh Ghost instance for automatic isolation
Applied to files:
agent-docs/testing.md
📚 Learning: 2025-11-26T11:05:59.314Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/shade/AGENTS.md:0-0
Timestamp: 2025-11-26T11:05:59.314Z
Learning: After integrating ShadCN components, run `yarn lint`, `yarn test`, and verify in Storybook before merging
Applied to files:
apps/shade/docs/shadcn-workflow.mdapps/shade/AGENTS.md
📚 Learning: 2025-11-26T11:05:59.314Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/shade/AGENTS.md:0-0
Timestamp: 2025-11-26T11:05:59.314Z
Learning: When adding new UI components, prefer ShadCN first: search for an equivalent and add via `npx shadcnlatest add <component>`
Applied to files:
apps/shade/docs/shadcn-workflow.mdapps/shade/AGENTS.md
📚 Learning: 2025-11-26T11:05:59.314Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/shade/AGENTS.md:0-0
Timestamp: 2025-11-26T11:05:59.314Z
Learning: Applies to apps/shade/**/*.stories.{ts,tsx} : Storybook stories for new components should include an overview explaining what the component does and its primary use case
Applied to files:
apps/shade/docs/shadcn-workflow.mdapps/shade/AGENTS.md
📚 Learning: 2025-11-26T11:05:59.314Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/shade/AGENTS.md:0-0
Timestamp: 2025-11-26T11:05:59.314Z
Learning: Applies to apps/shade/src/components/ui/**/*.{ts,tsx} : Atomic UI components should be placed in `src/components/ui/*` and each component must have a corresponding `*.stories.tsx` file next to it for Storybook documentation
Applied to files:
apps/shade/docs/shadcn-workflow.mdapps/shade/AGENTS.md
📚 Learning: 2025-11-26T11:05:59.314Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/shade/AGENTS.md:0-0
Timestamp: 2025-11-26T11:05:59.314Z
Learning: Applies to apps/shade/src/index.ts : Place new UI components under `src/components/ui` and export them from `src/index.ts`
Applied to files:
apps/shade/docs/shadcn-workflow.mdapps/shade/AGENTS.md
📚 Learning: 2025-11-26T11:05:59.314Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/shade/AGENTS.md:0-0
Timestamp: 2025-11-26T11:05:59.314Z
Learning: Applies to apps/shade/src/components/**/*.{ts,tsx} : Use `PascalCase` for component identifiers in filenames while keeping ShadCN-generated files in kebab-case
Applied to files:
apps/shade/docs/shadcn-workflow.md
📚 Learning: 2025-11-25T11:58:51.652Z
Learnt from: ibalosh
Repo: TryGhost/Ghost PR: 25525
File: apps/shade/src/shade-app.tsx:4-4
Timestamp: 2025-11-25T11:58:51.652Z
Learning: In apps/shade, the app wrapper file should be named `src/shade-app.tsx` (kebab-case) while the component itself is exported as `ShadeApp` (PascalCase). Context providers should be placed in `src/providers/*` using kebab-case filenames.
Applied to files:
apps/shade/docs/shadcn-workflow.mdapps/shade/AGENTS.md
📚 Learning: 2025-11-26T11:05:59.314Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/shade/AGENTS.md:0-0
Timestamp: 2025-11-26T11:05:59.314Z
Learning: Applies to apps/shade/src/components/**/*.{ts,tsx} : Use Tailwind CSS scoped via `.shade` class; dark mode uses `.dark`
Applied to files:
apps/shade/docs/shadcn-workflow.mdapps/shade/AGENTS.md
📚 Learning: 2025-11-26T11:05:59.314Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/shade/AGENTS.md:0-0
Timestamp: 2025-11-26T11:05:59.314Z
Learning: Never overwrite existing Shade components during `npx shadcnlatest add <name>` prompts; choose 'No' when asked to overwrite
Applied to files:
apps/shade/docs/shadcn-workflow.md
📚 Learning: 2025-11-26T11:05:59.314Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/shade/AGENTS.md:0-0
Timestamp: 2025-11-26T11:05:59.314Z
Learning: For new UI components, prioritize comprehensive Storybook stories; add focused unit tests where they provide real value (e.g., hooks, utils, logic-heavy parts)
Applied to files:
apps/shade/docs/shadcn-workflow.mdapps/shade/AGENTS.md
📚 Learning: 2025-11-26T11:05:59.314Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/shade/AGENTS.md:0-0
Timestamp: 2025-11-26T11:05:59.314Z
Learning: Applies to apps/shade/**/*.stories.{ts,tsx} : Storybook stories should demonstrate key variants and states (sizes, disabled/loading, critical props) with minimal but representative examples
Applied to files:
apps/shade/docs/shadcn-workflow.mdapps/shade/AGENTS.md
📚 Learning: 2025-11-26T11:05:59.314Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/shade/AGENTS.md:0-0
Timestamp: 2025-11-26T11:05:59.314Z
Learning: Always work on a fresh branch and commit a clean baseline before running ShadCN installer so changes can be easily reverted
Applied to files:
apps/shade/docs/shadcn-workflow.md
📚 Learning: 2025-11-24T17:28:38.037Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T17:28:38.037Z
Learning: Reference agents must define the agent's purpose, capabilities, and expected inputs/outputs in documentation
Applied to files:
apps/shade/CLAUDE.mdagent-docs/how_to_write_an_agents_md.md
📚 Learning: 2025-11-24T17:28:38.037Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T17:28:38.037Z
Learning: Reference agents must be version-controlled with clear change history and backward compatibility considerations
Applied to files:
apps/shade/CLAUDE.mdAGENTS.mdagent-docs/how_to_write_an_agents_md.md
📚 Learning: 2025-11-24T17:28:38.037Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T17:28:38.037Z
Learning: Reference agents should have a naming convention following the pattern: [Namespace][Agent Type] (e.g., MyNamespaceReferenceAgent)
Applied to files:
apps/shade/CLAUDE.md
📚 Learning: 2025-11-24T17:29:43.865Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: e2e/AGENTS.md:0-0
Timestamp: 2025-11-24T17:29:43.865Z
Learning: Applies to e2e/**/*.test.ts : Never use hard-coded waits like `waitForTimeout()`
Applied to files:
e2e/AGENTS.md
📚 Learning: 2025-11-24T17:29:43.865Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: e2e/AGENTS.md:0-0
Timestamp: 2025-11-24T17:29:43.865Z
Learning: Applies to e2e/**/*.test.ts : Never use `networkidle` in waits
Applied to files:
e2e/AGENTS.md
📚 Learning: 2025-11-24T17:29:43.865Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: e2e/AGENTS.md:0-0
Timestamp: 2025-11-24T17:29:43.865Z
Learning: Ensure tests have fresh Ghost instance isolation (automatic) and do not create test dependencies where Test B needs Test A
Applied to files:
e2e/AGENTS.md
📚 Learning: 2025-11-24T17:29:43.865Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: e2e/AGENTS.md:0-0
Timestamp: 2025-11-24T17:29:43.865Z
Learning: Applies to e2e/**/*.test.ts : Each test should represent one scenario only - never mix multiple scenarios in a single test
Applied to files:
e2e/AGENTS.md
📚 Learning: 2025-11-24T17:29:43.865Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: e2e/AGENTS.md:0-0
Timestamp: 2025-11-24T17:29:43.865Z
Learning: Applies to e2e/**/*.test.ts : Use factory pattern for all test data creation instead of hard-coded data or direct database manipulation
Applied to files:
e2e/AGENTS.md
📚 Learning: 2025-11-24T17:29:43.865Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: e2e/AGENTS.md:0-0
Timestamp: 2025-11-24T17:29:43.865Z
Learning: Applies to e2e/**/*.test.ts : Never use CSS/XPath selectors - only use semantic locators or data-testid
Applied to files:
e2e/AGENTS.md
📚 Learning: 2025-11-10T11:30:41.316Z
Learnt from: rob-ghost
Repo: TryGhost/Ghost PR: 25357
File: apps/admin/test-utils/test-helpers.ts:6-12
Timestamp: 2025-11-10T11:30:41.316Z
Learning: In apps/admin/test-utils/test-helpers.ts, the waitForQuerySettled helper is intentionally designed to timeout for idle/disabled queries. It should only treat queries as settled when they reach a terminal state (isSuccess or isError) and are not fetching. This ensures tests properly wait for active queries to complete.
Applied to files:
e2e/AGENTS.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Frontend dev servers and foundation libraries run on host machine during `yarn dev:forward`, while Ghost Core backend, MySQL, Redis, Mailpit, and Caddy run in Docker
Applied to files:
agent-docs/docker-development.mdagent-docs/architecture.mdagent-docs/analytics.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Run `yarn docker:dev` to start Ghost in Docker with hot reload
Applied to files:
agent-docs/docker-development.mdagent-docs/analytics.md
📚 Learning: 2025-11-25T13:09:33.918Z
Learnt from: jonatansberg
Repo: TryGhost/Ghost PR: 25485
File: compose.dev.yaml:0-0
Timestamp: 2025-11-25T13:09:33.918Z
Learning: In the Ghost Docker Compose development setup (compose.dev.yaml), the analytics service (ghost/traffic-analytics:1.0.20) requires `platform: linux/amd64` to be explicitly set, as this platform specification is necessary for now.
Applied to files:
agent-docs/docker-development.mdagent-docs/analytics.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Use `yarn dev:forward` for hybrid Docker + host development with backend in Docker and frontend dev servers on host
Applied to files:
agent-docs/docker-development.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Use Docker Compose file composition for optional services: `yarn dev:analytics` for Tinybird, `yarn dev:storage` for MinIO, `yarn dev:all` for all optional services
Applied to files:
agent-docs/docker-development.mdagent-docs/analytics.md
📚 Learning: 2025-05-27T18:08:00.458Z
Learnt from: cmraible
Repo: TryGhost/Ghost PR: 23546
File: compose.yml:58-59
Timestamp: 2025-05-27T18:08:00.458Z
Learning: The Ghost Docker Compose setup has two independent profiles: `ghost` profile (v0, runs all apps in a single container) and `split` profile (work in progress, runs Ghost server, admin, and frontend apps in separate services). The `split` profile will eventually replace `ghost` as the default.
Applied to files:
agent-docs/docker-development.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Run `yarn docker:build` to build Docker images and delete ephemeral volumes
Applied to files:
agent-docs/docker-development.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Run `yarn docker:reset` to reset all Docker volumes and restart services
Applied to files:
agent-docs/docker-development.md
📚 Learning: 2025-05-27T18:08:00.458Z
Learnt from: cmraible
Repo: TryGhost/Ghost PR: 23546
File: compose.yml:58-59
Timestamp: 2025-05-27T18:08:00.458Z
Learning: Services that are dependencies for both Ghost Docker Compose profiles (`ghost` and `split`) need to include both profiles in their `profiles` configuration to ensure they start correctly under either profile.
Applied to files:
agent-docs/docker-development.md
📚 Learning: 2025-12-01T08:42:35.294Z
Learnt from: jonatansberg
Repo: TryGhost/Ghost PR: 25552
File: e2e/helpers/environment/service-managers/dev-ghost-manager.ts:210-247
Timestamp: 2025-12-01T08:42:35.294Z
Learning: In e2e/helpers/environment/service-managers/dev-ghost-manager.ts, the hardcoded volume name 'ghost-dev_shared-config' at line 231 is intentional. E2E tests run under the 'ghost-dev-e2e' project namespace but deliberately mount the shared-config volume from the main 'ghost-dev' project to access Tinybird credentials created by yarn dev:forward. This is cross-project volume sharing by design.
Applied to files:
agent-docs/docker-development.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Admin-x React apps build to `apps/*/dist` using Vite, which are then copied by `ghost/admin/lib/asset-delivery` to `ghost/core/core/built/admin/assets/*`
Applied to files:
agent-docs/architecture.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Ghost admin serves admin-x apps from `/ghost/assets/{app-name}/{app-name}.js` URLs
Applied to files:
agent-docs/architecture.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: When working on Admin UI features, build in React using `apps/admin-x-*` or `apps/posts` apps
Applied to files:
agent-docs/architecture.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Use React with Vite for Admin app development (admin-x-settings, admin-x-activitypub, posts, stats)
Applied to files:
agent-docs/architecture.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Ember admin uses `AdminXComponent` to dynamically import React apps with Suspense and error boundaries
Applied to files:
agent-docs/architecture.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Public UI apps (Portal, Comments UI, Signup Form, Sodo Search, Announcement Bar) should be built as UMD bundles for CDN distribution
Applied to files:
agent-docs/architecture.md
📚 Learning: 2025-11-03T12:33:31.093Z
Learnt from: kevinansfield
Repo: TryGhost/Ghost PR: 25320
File: apps/admin/src/layout/app-sidebar/NavHeader.tsx:10-10
Timestamp: 2025-11-03T12:33:31.093Z
Learning: The Ghost admin apps (apps/admin/**) do not use SSR, so accessing browser APIs like `navigator`, `window`, or `document` at module load time is safe and does not require typeof guards.
Applied to files:
agent-docs/architecture.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Core Ghost backend logic should be placed in `ghost/core/core/server/` directory structure organized by purpose (api, services, models, data/schema, etc.)
Applied to files:
agent-docs/architecture.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Applies to ghost/i18n/locales/en/ghost.json : Add UI translations to `ghost/i18n/locales/en/ghost.json` for Admin UI features
Applied to files:
agent-docs/architecture.md
📚 Learning: 2025-08-11T19:39:00.428Z
Learnt from: kevinansfield
Repo: TryGhost/Ghost PR: 24651
File: ghost/core/test/utils/urlUtils.js:53-57
Timestamp: 2025-08-11T19:39:00.428Z
Learning: In Ghost's test utilities, when fixing specific issues like async behavior, it's preferred to maintain existing error handling patterns (even if suboptimal) to keep PRs focused on their primary objective. Error handling improvements can be addressed in separate, dedicated PRs.
Applied to files:
AGENTS.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Follow commit message format: max 80 chars on 1st line (past tense), blank 2nd line, then ref/fixes/closes with issue link, then context. Use emojis for user-facing changes (✨ feature, 🎨 improvement, 🐛 bug fix, 🌐 i18n, 💡 other)
Applied to files:
AGENTS.md
📚 Learning: 2025-11-24T17:28:51.262Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/comments-ui/.cursor/rules/playwright-e2e.mdc:0-0
Timestamp: 2025-11-24T17:28:51.262Z
Learning: Applies to apps/comments-ui/{package.json,**/.github/workflows/**,**/playwright.config.{ts,js},**/*.{sh,bash}} : Set PLAYWRIGHT_REPORTER=list environment variable when running Playwright e2e tests as an AI agent for better parsing
Applied to files:
AGENTS.md
📚 Learning: 2025-08-01T12:44:07.467Z
Learnt from: niranjan-uma-shankar
Repo: TryGhost/Ghost PR: 24557
File: apps/admin-x-settings/src/components/settings/general/TimeZone.tsx:7-7
Timestamp: 2025-08-01T12:44:07.467Z
Learning: In Ghost development, PRs may depend on unpublished changes from SDK packages. When this occurs, TypeScript compilation errors for missing exports are expected and documented in the PR description until the dependency packages are published and updated. This is normal workflow for cross-repository feature development.
Applied to files:
AGENTS.md
📚 Learning: 2025-11-26T11:05:59.314Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/shade/AGENTS.md:0-0
Timestamp: 2025-11-26T11:05:59.314Z
Learning: Commit messages must follow the structure: 1st line ≤ 80 chars in past tense starting with Fixed/Changed/Updated/Improved/Added/Removed/Reverted/Moved/Released/Bumped/Cleaned; 2nd line blank; 3rd line with magic word (ref/closes) + absolute issue URL; 4th+ lines explaining the 'why'/context
Applied to files:
AGENTS.md
📚 Learning: 2025-11-25T14:28:50.351Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T14:28:50.351Z
Learning: Analytics using Tinybird should reference scripts in `ghost/core/core/server/data/tinybird/scripts/` and datafiles in `ghost/core/core/server/data/tinybird/`
Applied to files:
agent-docs/analytics.md
📚 Learning: 2025-11-26T11:05:59.314Z
Learnt from: CR
Repo: TryGhost/Ghost PR: 0
File: apps/shade/AGENTS.md:0-0
Timestamp: 2025-11-26T11:05:59.314Z
Learning: Applies to apps/shade/src/components/features/**/*.{ts,tsx} : Higher-level, opinionated components (e.g., PostShareModal, SourceTabs) should be placed in `src/components/features/*`
Applied to files:
apps/shade/AGENTS.md
🪛 LanguageTool
AGENTS.md
[uncategorized] ~76-~76: The official name of this software platform is spelled with a capital “H”.
Context: ...gress. Always follow the PR template in .github/PULL_REQUEST_TEMPLATE.md and the contr...
(GITHUB)
[uncategorized] ~76-~76: The official name of this software platform is spelled with a capital “H”.
Context: ...MPLATE.mdand the contributor guide in.github/CONTRIBUTING.md`. The PR template asks...
(GITHUB)
agent-docs/react-query.md
[style] ~58-~58: The double modal “Requires specialized” is nonstandard (only accepted in certain dialects). Consider “to be specialized”.
Context: ...own it - Can become outdated - Requires specialized lifecycle management (loading, errors, ...
(NEEDS_FIXED)
[uncategorized] ~258-~258: Do not mix variants of the same word (‘co-locate’ and ‘colocate’) within a single text.
Context: ...s with queryOptions for reusability - Co-locate keys, functions, and configuration toge...
(EN_WORD_COHERENCY)
[grammar] ~1129-~1129: Ensure spelling is correct
Context: ...es won't confuse users (especially with placeholderData disappearing) - [ ] Ensure `staleTime: ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
agent-docs/how_to_write_an_agents_md.md
[style] ~82-~82: The adverb ‘sometimes’ is usually put before the verb ‘applies’.
Context: ... Task-Specific Instructions If it only applies sometimes, move it to a separate doc: ```markdow...
(ADVERB_WORD_ORDER)
🪛 markdownlint-cli2 (0.18.1)
agent-docs/docker-development.md
43-43: Bare URL used
(MD034, no-bare-urls)
44-44: Bare URL used
(MD034, no-bare-urls)
47-47: Bare URL used
(MD034, no-bare-urls)
48-48: Bare URL used
(MD034, no-bare-urls)
49-49: Bare URL used
(MD034, no-bare-urls)
agent-docs/react-query.md
960-960: Emphasis style
Expected: asterisk; Actual: underscore
(MD049, emphasis-style)
960-960: Emphasis style
Expected: asterisk; Actual: underscore
(MD049, emphasis-style)
980-980: Emphasis style
Expected: asterisk; Actual: underscore
(MD049, emphasis-style)
980-980: Emphasis style
Expected: asterisk; Actual: underscore
(MD049, emphasis-style)
1667-1667: Bare URL used
(MD034, no-bare-urls)
agent-docs/analytics.md
9-9: Bare URL used
(MD034, no-bare-urls)
agent-docs/how_to_write_an_agents_md.md
127-127: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
139-139: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Admin-X Settings tests
- GitHub Check: Build & Push
🔇 Additional comments (14)
apps/shade/docs/shadcn-workflow.md (1)
1-37: Well-structured ShadCN workflow documentation.The guide provides clear, actionable steps for component integration with appropriate guardrails. Verification checklist with yarn commands (lint, test, storybook) aligns with learnings on pre-merge validation. Based on learnings, the workflow correctly emphasizes never overwriting existing components and using clean branches for baseline commits.
agent-docs/how_to_write_an_agents_md.md (1)
39-91: Comprehensive and well-reasoned guidance on progressive disclosure.This document effectively codifies the pattern being implemented across the PR. The WHAT/WHY/HOW structure, universal applicability principle, and anti-patterns section provide clear rationale for the documentation refactoring. The example showing bad vs. good patterns is particularly valuable for future contributors.
agent-docs/architecture.md (1)
1-35: Excellent architectural summary for agent context.The file provides precise, concise descriptions of system integration patterns—Admin Apps micro-frontend approach, Public Apps UMD deployment, i18n architecture, and critical Nx build ordering. This directly addresses what agents need to understand when working on Ghost features. Alignment with learnings on asset-delivery pipeline, Suspense/error boundaries, and build dependencies is strong.
agent-docs/react-query.md (2)
1-50: Comprehensive React Query reference for code review and implementation.This condensed reference from TkDodo's series provides actionable guidance across all major React Query patterns. The structured sections, code examples, and anti-patterns make this valuable for agents reviewing React Query usage. As part of the progressive disclosure pattern, this appropriately lives in agent-docs/ rather than cluttering a root AGENTS.md.
425-449: Excellent pattern guidance on select function stability.The code examples demonstrating external function definition vs. inline functions with
useCallbackfor select functions are particularly valuable for code review. This directly addresses performance pitfalls agents might introduce.apps/shade/AGENTS.md (1)
1-41: Excellent application of progressive disclosure pattern.The Shade AGENTS.md now focuses on project essentials (structure, commands, patterns) while deferring detailed workflows to agent-docs/ and local docs/. This directly implements the PR's goal of trimming verbose documentation. Cross-reference to
docs/shadcn-workflow.mdappropriately separates task-specific guidance. The@import alias guidance on line 34 addresses a common agent mistake.apps/shade/CLAUDE.md (1)
1-1: Correct symlink reference for agent compatibility.File establishes the
CLAUDE.md→AGENTS.mdreference as documented inagent-docs/how_to_write_an_agents_md.md(line 161). This ensures both Claude Code and other agent tools can locate Shade documentation.e2e/AGENTS.md (1)
99-114: Proper clarification of test anti-patterns.The DON'T section correctly lists testing pitfalls, with line 108 appropriately emphasizing avoiding
networkidlein waits. This aligns with learnings that prohibitnetworkidlein E2E tests due to flakiness. The comprehensive anti-pattern list (hard-coded waits, test dependencies, direct DB manipulation, mixed scenarios) provides clear guidance for agents writing tests.agent-docs/testing.md (1)
1-42: Clear testing documentation with good progressive disclosure.The guide effectively provides quick reference commands alongside delegated references to
e2e/AGENTS.mdfor deeper patterns and debugging. The test organization table clarifies runner selection across the monorepo. The structure and commands align well with the PR goal of lean essentials in root, detailed guidance inagent-docs/.agent-docs/docker-development.md (1)
1-54: Strong Docker development documentation aligned with team learnings.The hybrid setup explanation clearly delineates what runs in Docker vs. on the host, matching established patterns. Commands, service URLs, and optional composition all align with documented learnings. The reference to
yarn docker:clean && yarn docker:buildfor troubleshooting is practical.AGENTS.md (4)
1-42: Excellent lean restructuring with clear progressive disclosure.The refactored root AGENTS.md successfully shifts from a comprehensive 237-line guide to a focused ~80-line reference, delegating architecture, Docker setup, testing, and analytics to
agent-docs/subdirectory. This aligns with the PR objective to improve AI context by avoiding cognitive overload from overly verbose documentation. The monorepo structure section is now clearer, distinguishing admin apps, public apps, and foundation libraries.
66-72: Commit message format guidance aligns with project learnings.The specified format—max 80 character summary (past tense, emoji if user-facing), blank line, then
fixes/closeswith issue link, then context paragraph—matches documented project standards. This clarity is valuable for agents and human contributors alike.
83-85: New Agent Attribution policy clarifies contribution workflow.The explicit guidance against AI attribution markers (
co-authored-by,generated-by, etc.) in commits and PRs prevents unnecessary metadata bloat and clarifies that AI-assisted work is the team's work. This is a good addition to the guidelines.
44-50: All cross-referenced files inagent-docs/exist and are properly structured. No action needed.
Agent documentation had grown verbose and included task-specific details that diluted the core guidance. Following the progressive disclosure pattern, detailed information now lives in dedicated files under agent-docs/, keeping the root AGENTS.md focused on universally-applicable essentials. This also adds a React Query reference guide to support the ongoing migration to React admin apps, and clarifies expectations around commit messages and attribution.
rob-ghost
force-pushed
the
docs/improve-agents-md-documentation
branch
from
e714f2e to
6146263
Compare
E2E Tests FailedTo view the Playwright test report locally, run: REPORT_DIR=$(mktemp -d) && gh run download 19892725495 -n playwright-report -D "$REPORT_DIR" && npx playwright show-report "$REPORT_DIR" |
Why are you making it?
The root AGENTS.md had grown to 237 lines and included task-specific details like Docker port numbers, exhaustive command lists, and architecture diagrams. Research on effective agent documentation suggests that verbose files get uniformly ignored—agents are instructed that context "may or may not be relevant," so irrelevant content teaches them to skip everything.
What does it do?
Applies the progressive disclosure pattern: the root AGENTS.md is trimmed to ~80 lines of universally-applicable essentials (package manager, project structure, core commands). Detailed guidance moves to
agent-docs/where agents can reference it when working on specific tasks. Also adds a React Query reference guide, streamlines the shade AGENTS.md, and clarifies commit/PR conventions.Why is this something Ghost users or developers need?
Better agent documentation means more effective AI-assisted development. Agents that receive focused, relevant context make fewer mistakes and require less correction. The progressive disclosure pattern ensures agents always get the essentials while having access to detailed guidance when needed.
Reference
https://www.humanlayer.dev/blog/writing-a-good-claude-md