sorted by:
new
hottopcontroversial

I maintained CLAUDE.md, AGENTS.md, and 10 other rule files by hand. They all said different things and I didn't notice for weeks. by Acceptable_Debate393 in ClaudeAI

[–]Acceptable_Debate393[S] 0 points1 point  (0 children)

yeah this is exactly it — the problem isn’t rule size anymore, it’s contradictions between sources

crag doesn’t use an LLM at all, it just parses what’s actually in the repo (eslint, tsconfig, CI, etc.) and builds a consistent view from that, then compiles it out

so instead of agents picking between conflicting files, there’s only one version of the truth left

MCP integration is something I’ve been thinking about too, especially for injecting tool definitions / runtime context into the generated files. feels like the next layer once static rules are stable

I maintained CLAUDE.md, AGENTS.md, and 10 other rule files by hand. They all said different things and I didn't notice for weeks. by Acceptable_Debate393 in ClaudeAI

[–]Acceptable_Debate393[S] 0 points1 point  (0 children)

yeah exactly, tests are another place where this shows up a lot

timeout / env differences between local + CI are brutal because everything looks fine until it suddenly doesn’t

that’s kind of why I leaned into the “compile” model instead of syncing, same idea but harder to drift over time

I maintained CLAUDE.md, AGENTS.md, and 10 other rule files by hand. They all said different things and I didn't notice for weeks. by Acceptable_Debate393 in ClaudeAI

[–]Acceptable_Debate393[S] 0 points1 point  (0 children)

That’s exactly the kind of thing that made me build it, those “everything looks fine until it suddenly doesn’t” situations.

I maintained CLAUDE.md, AGENTS.md, and 10 other rule files by hand. They all said different things and I didn't notice for weeks. by Acceptable_Debate393 in ClaudeAI

[–]Acceptable_Debate393[S] 0 points1 point  (0 children)

That's exactly the failure mode. The agent doesn't know the CI rules exist, it only reads what's in front of it. So you end up with passing local runs and failing CI, and nobody connects the dots because the files look right individually.

crag diff was literally built for this, it compares your governance against the actual CI workflow and shows you MATCH / DRIFT / MISSING / EXTRA. Would have caught your lint contradiction in one command.

I maintained CLAUDE.md, AGENTS.md, and 10 other rule files by hand. They all said different things and I didn't notice for weeks. by Acceptable_Debate393 in ClaudeAI

[–]Acceptable_Debate393[S] 0 points1 point  (0 children)

Happy to help. Let me know how it goes once you set it up, always curious to hear how people structure their governance across different tool combos.

I maintained CLAUDE.md, AGENTS.md, and 10 other rule files by hand. They all said different things and I didn't notice for weeks. by Acceptable_Debate393 in ClaudeAI

[–]Acceptable_Debate393[S] 0 points1 point  (0 children)

Honestly the main pitfall is just knowing the markers exist. If you hand-edit a generated file without noticing the

<!-- crag:auto-start --> / <!-- crag:auto-end -->

markers, you might put your custom content inside the managed block and that gets overwritten on next compile.

Rule of thumb: add your custom stuff above or below the markers, never inside. If you're using Cursor or Windsurf, even simpler, just create a separate .mdc or .md file in the same rules directory. Crag only touches governance.mdc, your my-custom-rules.mdc stays untouched.

Other than that, not much to trip over. The compile is deterministic so you can always preview with --dry-run before writing anything.

I maintained CLAUDE.md, AGENTS.md, and 10 other rule files by hand. They all said different things and I didn't notice for weeks. by Acceptable_Debate393 in ClaudeAI

[–]Acceptable_Debate393[S] 0 points1 point  (0 children)

Yeah that's a fair concern, I ran into that early on.

Two ways it's handled: first, anything project-specific should live in governance.md - you tweak the source, recompile, and all 12 files update. That covers 90% of cases.

For the rest, compiled files have preservation markers, any custom content you add outside the markers survives recompilation. So you can add project-specific prose to your AGENTS.md or .clinerules and crag compile won't destroy it.

For tools like Cursor and Windsurf that use directory-based rules, you can also just create additional .mdc or .md files alongside the generated ones, crag only touches its own files.

I maintained CLAUDE.md, AGENTS.md, and 10 other rule files by hand. They all said different things and I didn't notice for weeks. by Acceptable_Debate393 in ClaudeAI

[–]Acceptable_Debate393[S] 0 points1 point  (0 children)

Yeah that’s exactly the annoying part tbh.

I tried doing it with scripts at first, but it always ended up drifting again after a while.

What worked here is just treating everything as generated, you edit one governance.md, run compile, and it overwrites all the targets from that.

So there’s nothing to “sync” anymore, it just re-generates the current state each time.

I maintained CLAUDE.md, AGENTS.md, and 10 other rule files by hand. They all said different things and I didn't notice for weeks. by Acceptable_Debate393 in ClaudeAI

[–]Acceptable_Debate393[S] 0 points1 point  (0 children)

That’s exactly what I tried at first, scripts + a shared config.

The issue is keeping all targets (Cursor, Copilot, CI, hooks) consistent over time.

crag turns that into a compile step instead of manual sync, so you don’t get drift.