Skip to content

ADR-0019: AI-Assisted Development Workflow

Date: 2026-04-19 Status: Accepted

Context

jPipe is a research-grade open-source compiler. Its contributors care about code quality and long-term maintainability, but the project is small and reviewer bandwidth is limited. AI coding assistants have matured to the point where they can meaningfully accelerate implementation, code review, and quality maintenance — provided they are kept under human supervision.

Three AI tools are already in use across different phases of the development cycle:

  • Claude Code (Anthropic) — an agentic CLI assistant capable of planning and implementing multi-file changes.
  • GitHub Copilot — a GitHub-native assistant that generates PR metadata and reviews pull requests.
  • SonarCloud — an automated quality gate (ADR-0004) whose findings are surfaced to Claude Code via the SonarQube MCP server.

Without an explicit policy, AI contributions are invisible in the commit and review history, making it hard to audit what was generated versus what was deliberately written by a human.

Decision

AI assistants are permitted and encouraged in this project, subject to the human-in-the-loop constraints described below. All three tools are sanctioned for the specific roles outlined in the Workflow section.

Workflow

Implementation — Claude Code

New features, refactors, and bug fixes follow a plan-then-implement cycle:

  1. Enter plan mode (/plan in Claude Code) and describe the task.
  2. Claude produces a written implementation plan covering affected files, architectural trade-offs, and a verification step.
  3. A human reviewer reads the plan and either approves it, adjusts it, or rejects it. No code is written until the plan is approved.
  4. Claude implements the approved plan and runs mvn spotless:apply && mvn verify to confirm the build passes.
  5. The human reviews the resulting diff before committing.

SonarCloud quality-gate fixes follow the same cycle: the SonarQube MCP server surfaces open issues, Claude plans the remediation batch, the plan is approved, and Claude implements it.

Pull request metadata — GitHub Copilot

GitHub Copilot generates the PR title and body (summary + test plan) for every pull request. The author reads and edits the generated text before submitting.

Pull request review — GitHub Copilot

Copilot automatically comments on open pull requests. The developer triages each comment:

  • Irrelevant or incorrect — closed by the developer with a short explanation.
  • Valid but needs guidance — the developer writes a reply that frames the desired fix, then delegates implementation to Claude Code following the plan-then-implement cycle above.
  • Valid and trivial — fixed directly by the developer.

Rationale

  • Plan mode enforces human oversight. Requiring an approved plan before any code is written means the developer understands and owns every change, even if they did not type it.
  • Separation of roles keeps AI in a support position. Claude Code handles implementation; Copilot handles review commentary; humans make every architectural and acceptance decision.
  • Transparency via commit trailers. Co-authorship trailers (Co-Authored-By: Claude Code <noreply@anthropic.com>) in commit messages make AI involvement discoverable in git log without disrupting standard tooling.
  • Quality gate remains authoritative. SonarCloud is the objective measure of quality (ADR-0004). Using Claude to address SonarCloud findings — rather than to suppress them — keeps the gate meaningful.

Consequences

Human responsibility

The human who commits a change is fully responsible for it, regardless of whether it was written by a human or generated by an AI assistant. Approving a plan, reviewing a diff, and triggering a commit are acts of authorship. "Claude wrote it" is not a defence for a defect, a regression, or a quality-gate violation.

Mandatory disclosure

Any contribution that involved an AI assistant in a non-trivial way must be made explicit. Acceptable forms of disclosure:

  • A Co-Authored-By: Claude Code <noreply@anthropic.com> trailer in the commit message (preferred for implementation commits).
  • A Generated-By or Reviewed-By note in the PR description when the AI role was limited to review commentary or metadata generation (e.g. Copilot PR summaries).

Omitting disclosure when AI was meaningfully involved is not acceptable.

Other constraints

  • Contributors must not let an AI assistant commit or push autonomously; a human must review the diff and trigger the commit.
  • @SuppressWarnings annotations require explicit human approval before being added; Claude must always propose the real fix first (documented in CLAUDE.md).
  • The plan file produced in plan mode is ephemeral (not committed); the commit message is the durable record of intent.
  • Reviewers reading the git history should assume that commits with a Co-Authored-By: Claude Code trailer were planned and diff-reviewed by the committing developer, not blindly accepted.