I think AI-readiness needs to be more operational than just better docs and cleaner patterns.
In a large monorepo, the agent needs to know which commands are safe to run, which package or app a change belongs to, what setup is required, what tests validate that area, and what "ready" means for that path through the repo.
`CLAUDE.md` can help, but I would not make it the only source of truth. It can drift like a README. The stronger pattern is to make the repo's operational expectations explicit in a structured way, then let humans and agents consume the same source of truth.
A few practical things I'd look at:
clear ownership boundaries inside the monorepo, an obvious setup and verification path for each major package or app, standardized task names where possible, explicit safe commands and expected validation steps
This is very close to the problem I'm working on with Ota. It's an open-source CLI for repo readiness that uses an `ota.yaml` contract to make setup, readiness, execution, and agent-safe guidance explicit for humans, CI, automation, and agents.
For a monorepo, I'd think less in terms of "make the whole repo AI-ready" and more in terms of "make each contribution path explicit enough that an agent doesn't have to guess."
We've also pressure-tested Ota on the `n8n` repo here: https://github.com/n8n-io/n8n/pull/30714. The PR is closed, but the proposed contract is still there to inspect.
If you want to pressure-test your repo, share a simplified version of your setup and I can help think through what an Ota contract for it might look like.
In a large monorepo, the agent needs to know which commands are safe to run, which package or app a change belongs to, what setup is required, what tests validate that area, and what "ready" means for that path through the repo.
`CLAUDE.md` can help, but I would not make it the only source of truth. It can drift like a README. The stronger pattern is to make the repo's operational expectations explicit in a structured way, then let humans and agents consume the same source of truth.
A few practical things I'd look at: clear ownership boundaries inside the monorepo, an obvious setup and verification path for each major package or app, standardized task names where possible, explicit safe commands and expected validation steps
This is very close to the problem I'm working on with Ota. It's an open-source CLI for repo readiness that uses an `ota.yaml` contract to make setup, readiness, execution, and agent-safe guidance explicit for humans, CI, automation, and agents.
For a monorepo, I'd think less in terms of "make the whole repo AI-ready" and more in terms of "make each contribution path explicit enough that an agent doesn't have to guess."
We've also pressure-tested Ota on the `n8n` repo here: https://github.com/n8n-io/n8n/pull/30714. The PR is closed, but the proposed contract is still there to inspect.
If you want to pressure-test your repo, share a simplified version of your setup and I can help think through what an Ota contract for it might look like.
Ota: https://github.com/ota-run/ota Ota Examples: https://github.com/ota-run/examples