alunduil / alunduil/blog.alunduil.com

AGENTS.md carries the repo conventions, with CLAUDE.md a thin import

Aperta
#587 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
documentation
Lingua principale
Astro
Stelle
1
Fork
1
Merge medio
6h 34m
PR unite (30g)
118

Descrizione

## Summary

Split `CLAUDE.md` into an `AGENTS.md` carrying the repo conventions and a `CLAUDE.md` that imports it and keeps only what depends on Claude Code.

## Motivation

Most of `CLAUDE.md` describes the repo, not the harness: the tooling inventory, the two-tier link checking, the posting convention and its `pubDatetime` publication gate, the AstroPaper upstream boundary, the branch and deploy model, and the `idea` label automation. An agent that isn't Claude Code reads none of it, because only Claude Code reads that filename — so a Copilot or Codex session could edit AstroPaper theme files or append to a post's frontmatter with no idea either is governed.

## Scope

- `AGENTS.md` takes the repo-level conventions: Tooling, Posting convention, AstroPaper upstream, Branches and deploy, Idea issues, Scope discipline.
- `CLAUDE.md` becomes an `@AGENTS.md` import plus the genuinely Claude-Code-specific material.
- Add `AGENTS.md` to `.vale.ini` so it lints under the same rules `CLAUDE.md` gets today.

## Acceptance criteria

- [ ] `AGENTS.md` carries the repo conventions
- [ ] `CLAUDE.md` imports it and states nothing another agent also needs
- [ ] `.vale.ini` covers `AGENTS.md`
- [ ] The rule for adding a future tool config is written down
- [ ] Pre-commit passes

## Gotcha

This repo has the largest genuinely Claude-Code-specific share of any in the fleet, so it's a split rather than a rename. The Portability section is about Claude Code on the web not carrying `~/.claude/CLAUDE.md`; the Skills section catalogues `.claude/skills/`; Voice points at `.claude/voice.md`. All three stay in `CLAUDE.md`.

Watch the Portability rule while splitting: it exists because web sessions load only the checkout. An `@AGENTS.md` import is a repo-relative path, so it travels — but confirm that rather than assuming it.

## Additional context

Reference implementation: [dungeon-studio/genshin.dungeon.studio#1417](https://github.com/dungeon-studio/genshin.dungeon.studio/pull/1417), closing [#877](https://github.com/dungeon-studio/genshin.dungeon.studio/issues/877) there.

- [GitHub: add repository custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) — Copilot's cloud agent reads `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`.
- [Claude Code: AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) — Claude Code reads only `CLAUDE.md`, and prescribes the `@AGENTS.md` import for this case.

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.