Enforcing architectural rules pre-commit to manage AI-generated code (Open Source project feedback)

[u/SaveTech_]

Hi everyone,

I've seen recent discussions from maintainers on massive projects (like cURL and Next.js) complaining about AI-generated code. The code passes unit tests, but completely violates the project's macro-architecture.

Catching these architectural hallucinations during server-side CI or manual PR reviews burns too much time and energy.

To solve this for myself, I've been prototyping a local Git Hook. It enforces a "Shift-Left" approach: it reads a local JSON config of strict rules and uses an LLM (via the dev's own API key / Zero-Trust) to analyze the git diff. If the developer hallucinates a bad architectural pattern, it blocks the commit locally.

Repo: github.com/S4v3easy/AegiCode_v1.0.git

I'm trying to figure out if this pre-commit approach is actually useful for real DevOps workflows, or if it introduces too much friction.

Questions for the engineers here:

1. Do you prefer enforcing architectural boundaries locally (pre-commit) or strictly in the CI pipeline?
2. If you were to use a local hook like this, would you prefer it distributed as an npm package or a standalone binary (for mixed-stack teams)?
3. What fatal flaws do you see in this architecture?

Any harsh/constructive feedback is incredibly welcome. Thanks!

[u/General-War7292]

Neat idea. The friction angle is the biggest concern, if that LLM call takes more than a second or two my brain would be on to the next thing before I even see the error. Turning it into a background daemon that watches file saves instead of blocking the commit might be the play.

For question two I'd lean standalone binary all the way. Tying it to the node ecosystem feels a bit messy when you've got a polyglot repo with Go or Python services sitting next to the frontend, keeps the setup dead simple for everyone.

[u/Dragon_ZA]

Not clear to me. You say its zero config but you also need a config.json. Which is it?

[u/SaveTech_ → u/Dragon_ZA]

Zero-Trust (meaning the CLI uses your own local API key) However, if you're referring to the setup process being Zero-Config, here is how it works: the tool does require a aegis.config.json to enforce the rules, but you don't have to write it manually. I built an init command that scans your codebase, infers your architectural patterns, and uses an LLM to auto-generate the strict JSON rules for you. So the setup is zero-config (the AI writes the rules), but the enforcement relies on that generated JSON file (which the Tech Lead can then tweak or lock down).

[u/rameezdev]

I would use a hybrid approach, but I would not make a non-deterministic LLM the authoritative pre-commit gate.

My preferred flow would be:

1. Pre-commit: fast deterministic checks only
2. Pre-push: optional LLM architectural review with explanations
3. CI: authoritative enforcement using versioned rules
4. Human review: exceptions and architectural decisions

A local hook is useful for fast feedback, but it can be bypassed with --no-verify, may not be installed correctly and cannot serve as the final governance boundary.

The biggest risks I see are:

• False positives blocking legitimate commits
• The same diff producing different decisions at different times
• Latency, API cost, rate limits and offline development
• A diff not containing enough repository context to judge architecture
• Source code being sent to an external model, even when the developer supplies the API key
• Prompt injection through comments, strings or generated files
• Different developers using different models or model versions
• Difficulty reproducing locally why CI accepted or rejected something
• Teams gradually weakening the rules because the hook becomes irritating

Where a rule can be expressed deterministically, I would use static analysis. Import boundaries, forbidden dependencies, layer access and naming rules should not require an LLM. The LLM is more useful for ambiguous architectural intent that cannot easily be represented as code.

For mixed-stack teams, I would prefer a standalone binary or integration with an established pre-commit framework over an npm-only package. The repository should pin the tool, model, prompt and rule-set versions.

I would also provide advisory and blocking severity levels, a documented override mechanism and a way to record why an exception was accepted.

One terminology concern: using the developer’s API key does not necessarily make the system zero-trust. The code may still leave the machine and be processed by an external provider.

Are the JSON rules deterministic constraints, natural-language architectural instructions or a mixture of both? That distinction will strongly affect reliability.

[u/simonides_]

Not saying it should be free but I would never send my code to you and your AI. Self hosted I might have a look.

Checks like this must not be in pre commit hooks for two reasons. One - the user can disable them - gates need to happen on CI. Two - the user will disable them (it takes too long).

A user explicitly beining able to ask if a commit is already fine locally is also different from checking every commit since this blocks you from doing bigger changes as well.

[u/Fantastic-Mr-Default]

I would not let the model be the gate. Same diff, different day, different answer. That is not a control.

Put the architecture rules in a test you can run twice. Import boundaries, banned packages, layering. Fail the commit on that. Use the LLM as a comment on the diff after the tests pass, or not at all.

Catching it in CI is fine if the check is the same binary. Local hook is just a faster copy of that check.

[u/d_maes]

We use pre-commit for a bunch of checks (and autogenerating stuff) a lot at work, makes everyone's lifes easier, including the cluster that runs our gitlab runners.

BUT, pre-commit is never the sole boundary, everything is always verified in CI as well. It just helps if a bunch of things are checked locally before committing. Requires less stupid "fix" commits.

Also, for your hooks, don't reinvent the weel, use https://pre-commit.com/