CLAUDE.md

1# GitLab Project Guidelines
2 
3This file provides default AI agent instructions for the GitLab project.
4For customization options, see .ai/README.md.
5 
6## Local Overrides
7 
8Read @CLAUDE.local.md
9 
10## Context Loading
11 
12Load the following instruction files based on your current task:
13 
14- When working with **git, commits, or branches**: Read .ai/git.md
15- When working with **merge requests**: Read .ai/merge-requests.md
16- When **reviewing code or giving feedback**: Read .ai/code-review.md
17- When working with **CI/CD pipelines or `.gitlab-ci.yml`**: Read .ai/ci-cd.md
18- Before planning, implementing, OR reviewing code changes (including MR reviews), load the `gitlab-coding-principles` skill. This applies even when `.ai/code-review.md` is also loaded.
19 
20## Always-on rules
21 
22These apply to every task without needing a trigger:
23 
24- **Minimal fix** — apply the smallest change that solves the problem; do not expand scope across layers unless each layer is genuinely load-bearing
25- **Security fixes** — treat an issue as requiring a special security fix when the issue is confidential, has the `~security` label, and does NOT have the `~security-fix-in-public` label. When all three hold, DO NOT push to `gitlab-org/gitlab` (or any canonical repo); follow .ai/security-fixes.md
26- **Comment discipline** — cap comments at 1-3 lines and only add one when the why is non-obvious, like an invariant, a gotcha, or a tradeoff; delete comments that just restate the code, by default, not only when asked to trim
27- **Prose via subagent** — on a high-capability model, write human-facing prose (comments, MR/issue text, docs) via a mid-tier model subagent instead of typing it inline, since high-capability models tend to produce dense, jargon-heavy prose; brief it with the facts and constraints, then check its output for accuracy; on a mid-tier model, just write it directly
28 
29## Project Notes
30 
31- Default branch: `master`
32- GitLab has extensive CI/CD pipelines; be patient with pipeline results
33- Danger bot will comment on MRs with warnings; these are often non-blocking
34- This repository is very large; use targeted searches and glob patterns
35 
36## Fix Pipeline
37 
38### Job-name stop rules
39 
40Skip the failing job whose name equals `danger-review`. Do not fetch its logs or attempt to fix it. Continue investigating and fixing all other blocking failing jobs. Take no action only when every blocking failing job matches the filters specified.
41 
42### Merge requests
43 
44When opening a merge request as part of the Fix Pipeline flow (the title contains `[FixPipeline]`), apply labels based on the source of the run. The `<fix_pipeline_source>` block in your instructions contains exactly one of `merge_request`, `default_branch`, or `branch` — use it to determine which case applies.
45 
46- **`merge_request`**: apply `pipeline::tier-1`. This runs the cheaper tier-1 pipeline instead of the full default pipeline.
47- **`default_branch`**: apply both `pipeline::expedited` and `master:broken`. The expedited label fast-tracks the fix through CI by skipping non-essential jobs; the master:broken label marks the MR as a broken-master fix. Do not apply `pipeline::tier-1` in this case.
48- **`branch`**: apply `pipeline::tier-1`. Same treatment as the `merge_request` case — a fix MR for a non-default branch pipeline failure with no originating MR.
49 
50### Known failures and CI health context
51 
52Before diagnosing a failure, check whether it matches a known active incident. Three sources:
53 
54- [ci-health-incidents](https://gitlab.com/gitlab-org/quality/analytics/ci-health-incidents/-/issues?state=opened&label_name[]=ci-health%3A%3Aactive) — test file failures, failure categories, uncategorized job failures
55- [ci-health-systemic](https://gitlab.com/gitlab-org/quality/analytics/ci-health-systemic/-/issues?state=opened&label_name[]=ci-health%3A%3Aactive) — recurring systemic failures affecting many pipelines
56- [top flaky test files](https://gitlab.com/gitlab-org/quality/test-failure-issues/-/issues?state=opened&label_name[]=automation%3Atop-flaky-test-file&label_name[]=automation%3Abot-authored) — known flaky test files
57 
58Each ci-health incident title names the affected test file, failure category, or job. The flaky test issues title the affected spec file.
59 
60If the failing job or test matches an open issue in any of these:
61 
621. Link to the issue in your response or fix MR description.
631. Use it to guide your approach:
64   - **Infra failure** (`failed_to_pull_image`, `runner_system_failure`, etc.): no code fix is possible. Post a comment with the incident link. Do not open a fix MR.
65   - **Known flaky test**: the failure may be unrelated to the MR. Note this and link the issue, but still check whether the MR changes could have contributed.
66   - **Known failure category** (`docs_outdated`, `rake_outdated_translated_strings`, etc.): likely unrelated to the MR. Post a comment with the incident link rather than attempting a code fix.
67