Project Instructions Restructure

On this page

Context

A comprehensive audit of .claude/CLAUDE.md and related documentation revealed structural issues causing agents to miss critical workflow steps, stale data eroding trust in the docs, and formatting problems that bury important rules.

Most notably, an agent completed all code changes for a CI/CD overhaul but forgot to create a GitLab issue, commit, push, and open an MR until reminded — because the delivery protocol was scattered across multiple sections rather than presented as a prominent gate.

Status

All steps complete.

Steps

Step 1: Restructure CLAUDE.md

  • Add Delivery Protocol as the first subsection under Mandatory Rules — a clear "you are NOT done" gate

  • Extract Coding Conventions from the 21-item Workflow bullet list into a dedicated section (positioned before Git Workflow)

  • Add Documentation Update Checklist with concrete file list

  • Slim Workflow → Git Workflow (process-only, no coding rules)

  • Extract 125-line GitLab Standards to .claude/docs/gitlab-workflow.md, replace with summary + link

  • Move Rust 2024 gotchas from Known Issues into Coding Conventions

  • Remove duplicate worker identity / Keycloak UUID notes from Reference Data

  • Resolve contradictions: direct-to-main vs protected branches, self-merge vs sole developer

Step 2: Fix Stale Counts

File Stale Value Corrected Value

CLAUDE.md Phase 7

12 endpoints

14 endpoints

CLAUDE.md Phase 9

~111 subcommands

~144 subcommands

CLAUDE.md Reference Data

76 unit tests

48 unit tests

services.md reporting

Endpoints (12)

Endpoints (14)

services.md CLI

~80 subcommands, 10 untested modules

~144 subcommands, remove untested section

devstack.md

9 databases incl. craig_eligibility

8 databases (no eligibility)

CHANGELOG.adoc

Phase 3: 33, Phase 6: 12, Phase 7: 12, Phase 8: 11, Phase 9: 18 cmds

45, 18, 14, 21, 24 cmds

Step 3: Create .claude/docs/gitlab-workflow.md

Extract GitLab issue/MR/epic standards, closing protocol, labels, and Ultimate features reference from CLAUDE.md into a dedicated file.

Step 4: Update CONTRIBUTING.adoc sync note

Add note pointing to .claude/docs/gitlab-workflow.md as the authoritative source.

Verification

  • Delivery Protocol is first subsection under Mandatory Rules

  • Coding Conventions appears before Git Workflow

  • No duplicate information between sections

  • All cross-references resolve

  • Counts verified against codebase (14 reporting endpoints, 48 reference tests, 8 databases)

  • gitlab-workflow.md contains all content removed from CLAUDE.md

Edit this page · latest