Skip to content

docs(#4887): rework agent guides and add CLAUDE.md - #4888

Open
tenthe wants to merge 2 commits into
devfrom
4887-review-agent-instruction-files-and-add-a-claudemd
Open

docs(#4887): rework agent guides and add CLAUDE.md#4888
tenthe wants to merge 2 commits into
devfrom
4887-review-agent-instruction-files-and-add-a-claudemd

Conversation

@tenthe

@tenthe tenthe commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

Purpose

Overview

This PR reworks the repository's agent instruction files so that they carry the facts an AI coding agent cannot derive from the code, and adds a CLAUDE.md so Claude Code loads them. The root guide now states the toolchain, build and CI contract; the module guides gain concrete recipes; duplicated content across the UI and design docs is consolidated with an explicit precedence order.

Changes

  • Adds CLAUDE.md, which imports AGENTS.md and explains that nested guides must be read before editing in their directories.
  • Rewrites the root AGENTS.md around the toolchain (JDK 25 build, Java 17 language level), the fast test loop versus the root verify that alone runs the license check, code standards, commit conventions and an index of all nested guides.
  • Moves the security-researcher procedure out of the root guide into a security-triage skill under .claude/skills/, so it loads only for vulnerability work.
  • Adds recipes to the module guides: adding a migration (service-core), an endpoint (rest), an extension (extensions) and a storage type (storage-couchdb); removes the per-module validation sections now covered by the root.
  • Adds guides for the Python and Go clients, covering their toolchains and CI gates.
  • Cross-links DESIGN.md, PRODUCT.md, ui/STYLEGUIDE.md and ui/AGENTS.md with a stated hierarchy (DESIGN.md is normative for tokens and rules), corrects the UI component list and layout package name, and removes verbatim duplicates.
  • Exempts CLAUDE.md and .claude/** from the RAT license check, matching the existing AGENTS.md rule.

Remarks

PR introduces (a) breaking change(s): yes

PR introduces (a) deprecation(s): yes

@tenthe tenthe linked an issue Sep 8, 2026 that may be closed by this pull request
@github-actions github-actions Bot added dependencies Pull requests that update a dependency file ui Anything that affects the UI documentation Everything related to documentation testing Relates to any kind of test (unit test, integration, or E2E test). labels Sep 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dependencies Pull requests that update a dependency file documentation Everything related to documentation testing Relates to any kind of test (unit test, integration, or E2E test). ui Anything that affects the UI

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Review agent instruction files and add a CLAUDE.md

1 participant