DEV Community

Nicolas
Nicolas

Posted on

One architecture, one set of guidelines, for all your projects?

#opensource #documentation #ai #productivity

Ten repos, ten architectures

Open any three repositories at your company. One uses a service layer, one puts SQL in the route handlers, one has a utils/ folder that does everything. The buttons are three shades of blue. Each repo has its own CLAUDE.md or AGENTS.md, copied from another one six months ago and edited since.

Then someone decides: "From now on, every API returns errors in this format." That decision lands in a meeting, then a wiki page, then maybe in two of the ten CLAUDE.md files. The coding assistants in the other eight repos never hear about it.

And the docs? They were right the day they shipped. Nobody updates the page after the next refactor, because nobody remembers it exists.

Coding assistants made this worse and better at once. Worse, because they write code fast, in whatever style the local context suggests. Better, because they follow instructions very well, if every one of them gets the same instructions.

The idea: decide once, in one repository

I built Ohara, an open-source tool that puts every guideline and every doc in one GitHub repository. Coding assistants read it live through MCP. People read it on a website. Nothing is copied into each project.

The docs repository holds plain Markdown. Folders become the menu, and every change is a pull request:

guidelines/
  backend.md        # FastAPI structure, errors, state
  frontend.md       # React, paths, styles
  security.md
  testing.md
  git.md
design/
  brand.md
  style-guide.md    # tokens: color, type, spacing
  ui-kit.md         # component and screen specs
architecture/
  ...
Enter fullscreen mode Exit fullscreen mode

How Ohara connects the docs repository to every project

Assistants read the guidelines from Ohara when they work, and send doc changes back as pull requests. A human merges each one, and the website rebuilds on the merge.

Same architecture, guidelines, and UI in every project

Connect your assistant once:

claude mcp add --transport http ohara https://your-ohara/mcp
Enter fullscreen mode Exit fullscreen mode

Then run one command in each project:

/ohara:init
Enter fullscreen mode Exit fullscreen mode

The assistant finds the guidelines and docs that apply to this project, and writes them into .claude/rules/ohara.md (or AGENTS.md for other assistants), with the workflow to follow. It adds the server to .mcp.json, so the whole team gets it on the next pull. The rules file looks like this:

# Ohara instructions

Ohara is the source of truth for documentation and engineering guidelines.

Guidelines:
- `guidelines/backend`: Python and FastAPI: structure, style, errors.
- `guidelines/frontend`: React, TypeScript, and Vite.
- `design/ui-kit`: component and screen specs for the website.

Workflow:
- Before planning a change, read the guidelines that apply.
- Propose an architecture that follows them, and name them.
- After the change, check it against the guidelines.
Enter fullscreen mode Exit fullscreen mode

The file holds pointers, not copies. The assistant reads each guideline from Ohara when it works, so it always gets the merged version.

That is the part that changes the game. An architect changes guidelines/backend.md in a pull request. Once it is merged, the next task in every repository follows it. No copy-paste across ten CLAUDE.md files, no Slack announcement.

The UI works the same way. Put your design tokens, brand, and component specs in design/, and every frontend your assistants build uses the same colors, spacing, and components.

To check a project that already exists:

/ohara:review
Enter fullscreen mode Exit fullscreen mode

It reports each violation with its guideline, file, and line, and changes nothing unless you ask.

Docs that update and publish themselves

Guidelines flow into the code. The other direction matters as much: the code has to flow back into the docs.

Docs live next to the code

A code repository can keep its own docs in docs/. Add a .ohara.yml at its root:

docs:
  - docs
Enter fullscreen mode Exit fullscreen mode

On each push to the default branch, Ohara syncs those pages into apps/<repo>/ of the website. Your docs change in the same pull request as your code, and they are published the moment it merges.

The assistant writes the doc update

After a change, the workflow in the rules file tells the assistant to update the docs in the same change. Or run it yourself:

/ohara:update
Enter fullscreen mode Exit fullscreen mode

The assistant compares the docs with the latest code changes. It edits the project's own docs in place, and proposes every other affected page, such as an architecture page or the API reference, through the propose_change tool.

All proposals from one code branch land in a single docs pull request. Branch feature/billing in repo api becomes branch api/feature/billing in the docs repository. The assistant puts its link in the code pull request, so the reviewer sees the code and its docs side by side.

AI writes. A human merges. Ohara never merges anything on its own.

Publishing is a merge

A merge to the docs repository triggers a rebuild. The website, the search index, and the MCP server all serve the new version. There is no build step to run and no deploy to remember.

Stale pages get flagged

Each page can say what code it describes:

---
owner: alice
covers: [acme/api:src/billing/*]
verified: 2026-10-01
---
Enter fullscreen mode Exit fullscreen mode

When a push changes src/billing/, Ohara flags the page with the changed files and a compare link. A page that nobody verified in 180 days is flagged too. Assistants see the flags through the stale_pages tool and propose the fix.

A feature, start to finish

Here is what a normal day looks like. You ask your assistant to add invoice exports to the api repo.

  1. It plans. It reads guidelines/backend, guidelines/security, and the billing docs from Ohara, proposes an architecture, and names the guidelines it relies on.
  2. You review the plan. Five minutes, before any code exists.
  3. It builds from the approved plan, then checks the result against the guidelines and fixes what does not follow them.
  4. It updates the docs. It edits docs/billing.md in the api repo, and proposes a change to the architecture page in the docs repository.
  5. You open one code pull request that links one docs pull request. The reviewer reads both together.
  6. You merge. The code ships, .ohara.yml syncs the project docs, and the docs merge rebuilds the website.

The next developer, in a different repo, asks about invoices. Their assistant reads the updated page. Nobody wrote a wiki page by hand.

Try it

Ohara is one Docker container, Apache-2.0, and your docs stay in your own GitHub repository.

curl -fsSLO https://raw.githubusercontent.com/ntrossat/ohara/main/compose.yml && docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Open http://localhost:8000. The setup page creates a GitHub App. Install it on your docs repository and your code repositories, then run /ohara:init in each project.

Access mirrors GitHub. A public docs repository makes a public website. A private one requires GitHub sign-in, and only people who can read the repository can read the docs.

If your repos have drifted apart, try it on two of them and let me know how it goes in the comments. And if it helps, a star on GitHub helps other teams find it.

Top comments (0)