Make AGENTS.md the canonical agent guide; CLAUDE.md imports it#92
Merged
Conversation
AGENTS.md becomes the canonical instructions file; CLAUDE.md is now a one-line @AGENTS.md import so the two never drift. Also folds the runs table audit-trail paragraph (previously only in CLAUDE.md) into AGENTS.md so no content is lost in the consolidation.
- Replace the rotted schema description (it claimed v4 + files PK (volume_id, path, blake3); v7→v8 rebuilt files to (folder_id, name, blake3) and current SchemaVersion is 13) with the invariant plus a pointer to where it's actually enforced: the files_blake3_immutable trigger and uniq_files_live_per_path index in store/migrations.go. - Keep the never-squash rule as a one-liner so the repo file stands alone for agents that don't see a personal global config. - Fold the PR Closes convention and merge rule into one section; drop the redundant restatement in the workflow. - Add the CI-equivalent local verify command. Net ~40% smaller with no loss of load-bearing guidance.
There was a problem hiding this comment.
Pull request overview
This PR consolidates agent instructions into a single canonical guide (AGENTS.md) and makes CLAUDE.md a lightweight import to prevent the two documents from drifting over time.
Changes:
- Replaces the existing multi-section
CLAUDE.mdcontent with an@AGENTS.mdimport. - Introduces
AGENTS.mdas the consolidated agent guide, including core data invariants, PR conventions, and the default “implement #N” workflow.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
CLAUDE.md |
Replaced the full guide with an @AGENTS.md import so CLAUDE-based tooling reads the canonical instructions. |
AGENTS.md |
Added the consolidated, trimmed agent guide to serve as the single source of truth across tools. |
Comments suppressed due to low confidence (1)
CLAUDE.md:2
- If the intent is for CLAUDE.md to be a single-line import, consider removing the extra blank line so tooling that expects a strict one-line file can’t be tripped up by trailing content.
@AGENTS.md
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+8
to
+13
| most one live (non-`superseded`) row per path. The same no-loss rule governs the | ||
| `runs` table and its history. The schema enforces it — the | ||
| `files_blake3_immutable` trigger and the `uniq_files_live_per_path` partial | ||
| unique index (`store/migrations.go`) — so any new feature (sync, prune, dedup, | ||
| GC) must preserve it: no deleting or overwriting history without an explicit, | ||
| opt-in retention policy. |
Owner
Author
There was a problem hiding this comment.
Good catch — fixed in 249059c. Split the paragraph so the schema enforcement (files_blake3_immutable trigger + uniq_files_live_per_path index) is scoped to files, and runs is now stated as a policy rule (no auto-prune; it's overwrite-in-place via FinishRun), not schema-enforced.
| - Forget `go mod tidy` after adding a dependency | ||
| - Keep names/visibility when moving code — re-evaluate | ||
|
|
||
| Before pushing, verify like CI: `go vet ./...`, `go test ./...`, `golangci-lint run`. |
Owner
Author
There was a problem hiding this comment.
Fixed in 249059c — dropped the "verify like CI" framing since the local check intentionally omits go build (per a standing rule to avoid leaving build artifacts in the repo). It's now just "Before pushing: ...".
- Separate the files schema invariant (enforced by the files_blake3_immutable trigger + uniq_files_live_per_path index) from the runs retention rule (policy, not schema — runs is overwrite-in-place via FinishRun). The prior wording implied the trigger/index governed both tables. - Drop the 'verify like CI' framing: CI also runs go build (and a wailsdesktop build), which the local check intentionally omits.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Consolidate the two agent-instruction files into one source of truth and trim it.
@AGENTS.mdimport. AGENTS.md (the cross-tool standard) becomes canonical; CLAUDE.md is now a one-line import so the two can't drift.filesPK(volume_id, path, blake3)", butmigrateV7ToV8rebuiltfilesto(folder_id, name, blake3)and currentSchemaVersionis 13. There is no single canonical schema file (fresh DBs apply a frozen v5 baseline then stepv6→v13), so pinning column lists in prose is inherently rot-prone. Now states the invariant and points at where it's actually enforced: thefiles_blake3_immutabletrigger anduniq_files_live_per_pathpartial unique index instore/migrations.go(stable names across rebuilds).Closes #Nconvention and the merge rule into one section; dropped the duplicate restatement in the workflow.go vet ./...,go test ./...,golangci-lint run.Why
The
runs-table audit-trail paragraph lived only in CLAUDE.md, and the self-reference differed — the files were already drifting. Folding everything into AGENTS.md with CLAUDE.md as an import makes drift impossible, and the schema description had already gone stale, which is the motivating example for not embedding schema specifics in instruction prose.No code or behavior changes — docs only.