Guidelines for Contributions and the Use of AI Tools in Coding and Code Review

[dsilhavy]

Status:

• Draft v1 for discussion

Guidelines for Contributions and the Use of AI Tools in Coding and Code Review

Purpose

This document sets out what 5G-MAG expects from any contribution to our reference tools.

The one rule everything else follows from

The contributor is the author. Whether a line of code came from your own fingers, a teammate's suggestion, a search result, or an AI assistant, submitting it as part of a pull request means you understand it, you tested it, and you stand behind it. Responsibility for a contribution's correctness, security, and IP cleanliness always stays with the human who submits it — it cannot be delegated to a tool.

A practical corollary: if you cannot explain how a piece of AI-generated code works, it is not ready to submit. When behavior turns out to be strange, "the AI wrote it" leaves reviewers to reverse-engineer the change from scratch — which costs the project far more than the generation saved.

Balance generation with review capacity

Code is now cheap to produce and expensive to review. When the person driving the AI is also the one fixing its mistakes, this roughly nets out. When reviewers are different people from the AI operator, the asymmetry becomes a resourcing problem: development runs ahead of review, a backlog of unreviewed PRs accumulates, and expert time is consumed unpicking machine-generated errors. Our expectations:

1. Match your submission rate to the project's review capacity. A growing queue of your own unreviewed PRs is a signal to pause generating and help review instead — reviewing others' PRs is a first-class contribution, and during busy periods it is often the most valuable one.
2. You absorb the cost of your tools' mistakes. If AI-generated code you submitted behaves strangely, the default expectation is that you investigate and fix it, not that reviewers unpick it for you.
3. Keep diffs minimal. AI assistants tend to "blow up" changes — rewriting adjacent code, reformatting, adding speculative abstractions. Moreover, AI tools add code that might be relevant for future contributions but has no concrete impact for the current contributions. Trim generated changes down to what the issue actually requires. A reviewer should never have to ask "why did this file change at all?"
4. Be especially careful where code implements a specification. AI tools make confident but wrong decisions about specs — sometimes because the specs themselves are imperfect or ambiguous. Verify generated code against the actual spec text (and version) yourself. If the spec is ambiguous, raise that as a finding on the relevant issue or in the Standards repository rather than letting the AI silently pick an interpretation.

Issues first, then pull requests

Every bug fix or feature in a PR should trace back to an issue that exists before the fix:

• One bug, one issue. Record each bug as its own issue so it can be investigated and confirmed (triaged) before the need for a fix is agreed. Summarizing bugs only in the PR description skips triage and puts the process the wrong way around.
• Composite PRs are fine — untraceable ones are not. A PR may fix several issues at once, provided each is referenced (e.g. Fixes #123, fixes #124).

Pull request structure and stacking

• Prefer small, incremental PRs scoped to one issue or one coherent feature. If a change can be split into independently reviewable pieces, split it.
• Every PR description must be self-contained: what it changes and why, on its own. A PR must never rely on the reader having absorbed earlier unmerged PRs to make sense — that leads to ever-growing implicit context and is not how PRs are supposed to work.
• If a PR builds on an earlier unmerged PR, set its base branch to the predecessor's branch, not development. The diff then shows only the new work, each PR stays reviewable in isolation, and when the predecessor merges, GitHub retargets the follow-up automatically. Say so explicitly in the description ("Stacked on XXX").

What we expect from every contribution

These apply regardless of how the code was produced:

1. You can explain it. You should be able to walk a reviewer through why the code works and why it's the right approach, not just that it runs.
2. It's tested. New behavior has test coverage where the repository has a test framework; changed behavior is verified against existing tests. "The AI said it should work" is not a substitute for running it.
3. It's scoped. The diff contains what the linked issue requires and nothing more.
4. It fits the codebase. Follows the repository's existing style, architecture, and conventions rather than introducing a parallel pattern because that's what the tool generated.
5. It's yours to give. You have the right to contribute it under the repository's license, and it doesn't knowingly include third-party code, patented techniques, or confidential material you're not authorized to share (see Licensing and IPR below).
6. It's reviewed like anything else. A pull request gets the same scrutiny and the same sign-off bar whether or not AI tools were involved anywhere in producing it.

Recommendations for using AI coding assistants

• Read before you submit. Review every AI-suggested change yourself before including it in a commit, the same way you'd review a snippet copied from a forum post or a colleague's suggestion.
• Test AI-generated code at least as thoroughly as hand-written code. It has no track record with your codebase yet — treat it accordingly.
• Use AI tools to raise your own bar, not to skip steps. Good uses: drafting boilerplate, suggesting tests, explaining an unfamiliar API, catching an obvious bug before you open a PR. Less good: pasting a whole feature request into a chat tool and submitting the output unread.
• Constrain the tool's scope. Point it at one issue or one feature at a time and reject unrelated changes it volunteers. Working release-by-release or feature-by-feature keeps generated changes aligned with what reviewers can absorb.
• Mentioning tool use is welcome, not required. If you'd like to note that a change was AI-assisted (e.g. a short note in the PR description), that's useful context for reviewers and we welcome it — but the review bar and your responsibility as author are the same either way.

Recommendations for using AI tools in code review

• Manually review and filter AI review output before posting it. Depending on the model, much of the raw output is noise; the operator curates it and communicates only the relevant findings. Posting an unfiltered AI review shifts the filtering burden onto the author.
• Post AI findings as individual, actionable comments, not as one monolithic report, so the author can evaluate each suggestion on its merits.
• The approving reviewer is accountable for the approval, regardless of what automated tooling flagged or didn't flag. AI review tools are a useful first pass, not a substitute for a human reviewer's sign-off.

tldr;

• You own what you submit. Whatever produced the code, you understand it, tested it, and are responsible for its correctness, security, and IP — if you can't explain it, it's not ready.
• Don't outpace review capacity. Throttle submissions, fix your own tools' mistakes, keep diffs minimal, and verify spec-implementing code against the actual spec text.
• Process: one issue per bug before the PR; small, self-contained PRs; stack follow-ups on the predecessor branch.
• Same bar for all code: explainable, tested, scoped, idiomatic (matching the patterns the repo already uses), license-clean. Disclosing AI use is welcome, not required.
• AI in review: filter the output, post individual actionable comments, and the approving human stays accountable.

[jordijoangimenez]

@dsilhavy, thanks for kick-starting this. It looks good.

It may be would be useful to make a distinction between using AI to fix an existing issue (this is very self-contained) vs developing new code where the functionalities do not exist (but the baseline does).

For the latter, I would like to propose a process on top of the generation of code and PRs. From the experience with MBS I think it is necessary to train the AI tool to first understand the specifications without the bias of taking a repo which exists, then understand the repositories which are within scope (e.g. pass all the rt-mbs- ones), audit the specification coverage per repo to see where the gaps are, then start implementing.

To make this practical, I am now about to push guidelines as a PR to the Standards2Deployments repository, that I would like to review as part of this process, they are aligned to the proposal here.

I would like to propose that the CLAUDE.md per repo (or any file assisiting AI-based implementation) is kept within Standards2Deployments rather than within each repo. I would like that the repo contains just the code but added value work stays private.

[dsilhavy]

Thanks @jordijoangimenez . Regarding:

I would like to propose that the CLAUDE.md per repo (or any file assisiting AI-based implementation) is kept within Standards2Deployments rather than within each repo. I would like that the repo contains just the code but added value work stays private.

From my understanding the CLAUDE.md file is specific to a repo and provides information about the repo itself that help Claude or other LLMs to not begin from zero each time. Meaning that each session starts with a fresh context window, and CLAUDE.md is the mechanism for carrying persistent instructions across sessions.

My main questions are:

• What kind of information would that generic markdown file in Standards2Deployments save?
• How do we link it to the relevant repos?

[jordijoangimenez]

Hi @dsilhavy,

I've pushed the examples here: https://github.com/5G-MAG/Standards2Deployments/tree/publish-guidelines/ai-development-guidelines

The first step is to import the framework into Standards2Deployments. Once it is in, the per-repository CLAUDE.md lives under projects/, named after the repository it governs, rather than in the component repository. The component repository then carries just the code.

For MBS that is projects/rt-mbs/, on the same branch, as a worked example:

rt-mbs-function.md, rt-libflute.md, rt-mbs-transport-function.md, rt-5gc-service-consumers.md,...

[dsilhavy]

Thanks @jordijoangimenez

I still struggle to grasp the complete architecture. I think if we use a structure like this we need to symlink the Claude files into the respective main repository. Because by default when we start Claude it will look for a CLAUDE.md file in the root of the repo. Also the name CLAUDE.md is a default name which we would need to use for all projects I think. Obviously the solution should not be limited to Claude it is a bit of a mess right now in general. We can add also an Agents.md or whichever name other LLms use by default.

[jordijoangimenez]

That is fine but then that file is gitignored and not pushed to a repo which should only contain the reference tool. Materials to assist the implementation should be hosted in Standards2Deployments.

In any case, if you import the AI guidelines framework, this will prevent creating any CLAUDE.md file and rely on the RULES.md