docs: add CLAUDE.md and .claude folder setup for contributor productivity by carlesarnal · Pull Request #7627 · Apicurio/apicurio-registry

carlesarnal · 2026-03-24T10:23:54Z

Summary

Set up the .claude folder following best practices to help contributors work more effectively with the Apicurio Registry codebase using Claude Code.

Root Cause

The repository had no CLAUDE.md content and the entire .claude directory was gitignored, preventing team-shared configuration from being committed. Contributors using Claude Code had no project-specific instructions, commands, or conventions available.

Changes

.gitignore: Replace blanket .claude ignore with specific ignores for personal files (settings.local.json, CLAUDE.local.md) so team config can be tracked
CLAUDE.md (102 lines): Concise project context — build commands, architecture, storage variants, conventions, gotchas
.claude/settings.json: Team-shared permission policies (allow Maven/git/gh, deny destructive commands and .env reads)
.claude/rules/ (6 files): Path-scoped coding conventions with YAML frontmatter:
- code-style.md — Java conventions derived from .checkstyle/checkstyle.xml
- testing.md — Unit/integration test patterns, storage variant coverage
- api-conventions.md — REST API patterns, SDK regeneration
- storage.md — Storage layer architecture and variant guidelines
- ui.md — React/TypeScript frontend build process
- security.md — OIDC, secrets, TLS considerations
.claude/commands/ (7 files): Project-specific slash commands:
- 5 refined: analyze-gh-issue, plan-implementation, implement-changes, review-pr, pr-description
- 2 new: run-tests (smart test runner), debug-ci-failure (CI diagnosis)
.claude/skills/ (3 workflows): Auto-invoked when context matches:
- security-review — triggers on auth/OIDC/secrets discussions
- storage-variant-guide — triggers when modifying storage layer
- sdk-update — triggers when REST API changes affect SDKs
.claude/agents/ (3 subagents): Specialized personas using sonnet model:
- code-reviewer — correctness, checkstyle, storage consistency
- security-auditor — auth, secrets, OIDC, TLS (read-only)
- ci-debugger — GitHub Actions failure diagnosis

Test plan

CLAUDE.md is under 200 lines (102 lines)
.claude/settings.local.json is NOT tracked in git
All 21 new files are committed and tracked
Verify commands work: /project:analyze-gh-issue, /project:run-tests, /project:debug-ci-failure
Verify rules activate only for matching file paths
Verify agents spawn with correct model and tool restrictions

…curio#7626) Replace blanket `.claude` ignore with specific ignores for personal files (settings.local.json, CLAUDE.local.md) so team-shared config (commands, rules, skills, agents, settings.json) can be tracked in git.

Concise project instructions (102 lines) covering build commands, architecture, storage variants, conventions, and gotchas.

…io#7626) Allow Maven, git read commands, and GitHub CLI. Deny destructive commands and .env file reads.

…o#7626) Six modular rule files with YAML frontmatter path scoping: - code-style.md (Java conventions from checkstyle.xml) - testing.md (unit/integration test patterns) - api-conventions.md (REST API patterns) - storage.md (storage layer architecture) - ui.md (React/TypeScript frontend) - security.md (OIDC, secrets, TLS)

…curio#7626) Five refined commands (analyze-gh-issue, plan-implementation, implement-changes, review-pr, pr-description) and two new commands (run-tests, debug-ci-failure).

…#7626) Three skills that Claude can invoke automatically when relevant: - security-review: triggers on auth/OIDC/secrets discussions - storage-variant-guide: triggers when modifying storage layer - sdk-update: triggers when REST API changes affect SDKs

…o#7626) Three agents using sonnet model for cost-efficient focused tasks: - code-reviewer: correctness, checkstyle, storage consistency - security-auditor: auth, secrets, OIDC, TLS (read-only) - ci-debugger: GitHub Actions failure diagnosis

jsenko · 2026-03-24T11:16:41Z

There is a lot of inline bash commands, which is fine but from my experience Claude is pretty good at using gh or git without guidance. It's fine to keep them, but some generic ones can be removed.

carlesarnal · 2026-03-24T11:27:57Z

There is a lot of inline bash commands, which is fine but from my experience Claude is pretty good at using gh or git without guidance. It's fine to keep them, but some generic ones can be removed.

Fair, although those have been extracted from the readmes, and, generally speaking, this is meant to streamline upstream contributions to the project.

EricWittmann · 2026-03-24T13:30:24Z

.claude/settings.json

+      "Bash(gh issue *)",
+      "Bash(gh pr *)",


I think this would allow issues and PR to be created, deleted, edited, etc. Do we want to allow all that by default?

Yes, since the comments we're shipping use some of those commands, I do think it makes sense.

EricWittmann · 2026-03-24T13:30:44Z

.claude/settings.json

+      "Bash(curl *)",
+      "Bash(wget *)",


Why deny curl and wget?

- Add PreToolUse hook to block edits to target/ and .env files - Add PostToolUse hook to auto-run checkstyle after Java file edits - Add Notification hook for macOS desktop alerts - Remove curl/wget from deny list (unnecessary, permission system prompts)

) - Add attribution config to disable co-authored-by in commits and PRs - Make notification hook cross-platform (macOS + Linux) - Optimize checkstyle hook to check only the edited file, not full module

EricWittmann · 2026-03-24T14:55:15Z

.claude/settings.json

+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/checkstyle-after-edit.sh",
+            "timeout": 60,
+            "statusMessage": "Running checkstyle"
+          }


How long does this take to run? I'm worried about it slowing down claude code even further.

I'll change it to be executed before any git commit command executed by claude, I think that's a fair compromise, wdyt?

EricWittmann · 2026-03-24T14:56:02Z

.claude/settings.json

+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/notify.sh"
+          }


Not sure I like this being enabled by default...

Agreed. I like it for me, but having it enabled for everyone is probably no the best idea..

EricWittmann · 2026-03-24T14:58:04Z

I love the agents, rules, and skills. 👍

The commands can be used or not used, so those are fine. I'm a little skeptical of some of the hooks though. I added some inline comments.

- Restrict gh permissions to read-only (view, list, diff, checks) - Remove checkstyle and notification hooks from default config - Document hooks as opt-in via settings.local.json in CLAUDE.md

This reverts commit 995d258.

- Move checkstyle from PostToolUse (every edit) to PreToolUse (before git commit only), checking staged Java files per module - Remove notification hook from default config, document as opt-in - Remove old checkstyle-after-edit.sh, add checkstyle-before-commit.sh

carlesarnal · 2026-03-26T08:28:34Z

@EricWittmann @jsenko any objection for merging this? I think it's a good compromise in it's current form, and we can evolve it over time if we think it's not serving us well.

jsenko · 2026-03-26T08:31:41Z

I've provided my feedback in the other channel, but I don't have any blocking objections.

EricWittmann · 2026-03-26T13:12:26Z

No objection.

carlesarnal added 7 commits March 24, 2026 11:12

docs: add CLAUDE.md with project context for Claude Code (Apicurio#7626)

a1904b1

Concise project instructions (102 lines) covering build commands, architecture, storage variants, conventions, and gotchas.

chore: add .claude/settings.json with team-shared permissions (Apicur…

ed0796c

…io#7626) Allow Maven, git read commands, and GitHub CLI. Deny destructive commands and .env file reads.

docs: add .claude/commands/ with project-specific slash commands (Api…

85141ed

…curio#7626) Five refined commands (analyze-gh-issue, plan-implementation, implement-changes, review-pr, pr-description) and two new commands (run-tests, debug-ci-failure).

carlesarnal force-pushed the issue-7626 branch from 19a4f3d to c8d015a Compare March 24, 2026 10:32

EricWittmann reviewed Mar 24, 2026

View reviewed changes

carlesarnal added 2 commits March 24, 2026 14:53

fix: improve hooks and disable co-authored-by attribution (Apicurio#7626

793481f

) - Add attribution config to disable co-authored-by in commits and PRs - Make notification hook cross-platform (macOS + Linux) - Optimize checkstyle hook to check only the edited file, not full module

EricWittmann reviewed Mar 24, 2026

View reviewed changes

carlesarnal added 3 commits March 25, 2026 09:09

fix: address PR review feedback (Apicurio#7626)

995d258

- Restrict gh permissions to read-only (view, list, diff, checks) - Remove checkstyle and notification hooks from default config - Document hooks as opt-in via settings.local.json in CLAUDE.md

Revert "fix: address PR review feedback (Apicurio#7626)"

d952947

This reverts commit 995d258.

carlesarnal merged commit a208749 into Apicurio:main Mar 26, 2026
29 checks passed

carlesarnal deleted the issue-7626 branch March 26, 2026 13:13

Conversation

carlesarnal commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Root Cause

Changes

Test plan

Uh oh!

jsenko commented Mar 24, 2026

Uh oh!

carlesarnal commented Mar 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

EricWittmann commented Mar 24, 2026

Uh oh!

carlesarnal commented Mar 26, 2026

Uh oh!

jsenko commented Mar 26, 2026

Uh oh!

EricWittmann commented Mar 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

carlesarnal commented Mar 24, 2026 •

edited

Loading