Ask HN: How to make a mono-repo AI-Ready?

3 pointskasnaka6d ago4 comments

The org is pushing for AI-readiness! We run a fairly large monorepo, part of that is a shared web-platform.

Our team is struggling with the inbound contributions to said web-platform from other teams seeing it as the perfect code to try out their new AI-tools on.

Our idea so far is that AI-Ready in this case is the same as Human-Ready. I.e. make the codebase understandable, structured, clean up any old patterns still lying around etc. With the additional of adding ClAUDE.md files describing correct patterns.

However, besides the "regular", look at shit and clean it, is there any tools, or smarter ways to make our codebase easier for other to contribute to given the new tools avaialable?

4 comments

B0BAI5d ago

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.

Ota: https://github.com/ota-run/ota Ota Examples: https://github.com/ota-run/examples

aqsa_sajjad6d ago

AI-ready is mostly just “good engineering hygiene”, but with a much stronger penalty for ambiguity.

LLMs amplify whatever already exists in the repo:

-good patterns become reusable, -inconsistent patterns become chaos generators.

muzani5d ago

Claude seems to do perfectly fine with monorepos and navigates them better than humans. GPT will get lost and repair the wrong code. Most tools will also look at what you worked on recently.

If it's difficult for humans, then that should be improved.

OutrageousTea6d ago

Honestly, if humans can easily understand the codebase, AI tools usually work better with it too. Clear structure, consistent patterns, and good docs go a long way.

j / k navigate · click thread line to collapse