Sync §5.7 Agent Context Files — Standard v1.46 #33
There are no files selected for viewing
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| # CLAUDE.md | ||
|
|
||
| @AGENTS.md | ||
|
|
||
| > Record project knowledge in `AGENTS.md`, not here. This file holds only | ||
| > Claude-Code-only context (Standard §5.7). | ||
|
|
||
| ## Claude Code specifics | ||
|
|
||
| - `microsoft-rust-guidelines` is `user-invocable: false` on purpose — it is the | ||
| mandatory auto-load Rust base and is hidden from the `/` menu by design. See | ||
| the editing rules in `AGENTS.md`; do not "fix" its absence from the menu. | ||
| - Skills reach Claude at `~/.claude/skills/<skill>`, one of the per-harness paths | ||
| Home Manager provisions (see "Local agent fan-out" in `AGENTS.md`). |
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| # CLAUDE.md | ||
|
|
||
| @AGENTS.md | ||
|
|
||
| > Record project knowledge in `AGENTS.md`, not here. This file holds only | ||
| > Claude-Code-only context (Standard §5.7). |
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,84 +1,67 @@ | ||
| # CLAUDE.md — <PROJECT_NAME> | ||
|
|
||
| <!-- | ||
| Spacecraft Software CLAUDE.md template, version 2.0.0. | ||
| License: GPL-3.0-or-later | ||
|
|
||
| Standard §5.7 governs this file. AGENTS.md is the authority: it holds | ||
| every project fact — build commands, invariants, layout, forbidden | ||
| patterns. This file imports it and adds ONLY what a non-Claude harness | ||
| cannot act on. | ||
|
|
||
| Do NOT copy, symlink, summarize, or mirror AGENTS.md here. If you find | ||
| yourself writing "keep these two files in sync," the split is wrong. | ||
|
|
||
| Do NOT duplicate the CLI Standard here either — those rules live in the | ||
| spacecraft-cli-standard and spacecraft-agentic-cli skills. | ||
|
|
||
| CLAUDE.md is REQUIRED even when it holds nothing else. Claude Code reads | ||
| CLAUDE.md, not AGENTS.md — a project with only an AGENTS.md gives a | ||
| Claude session no project context at all. With nothing Claude-only to | ||
| say, the heading + @AGENTS.md + the blockquote is the whole file. | ||
|
|
||
| Both AGENTS.md and CLAUDE.md are tracked. Neither may be gitignored, and | ||
| neither carries credentials, private hostnames, or personal filesystem | ||
| paths. | ||
| --> | ||
|
|
||
| @AGENTS.md | ||
|
|
||
| > Record project knowledge in `AGENTS.md`, not here. This file holds only | ||
| > Claude-Code-only context (skills, `.claude/`, slash commands, MCP client). | ||
|
|
||
| <!-- ===== Claude-only content below this line ===== --> | ||
|
|
||
| ## Skills to load | ||
|
|
||
| The following Spacecraft Software skills apply to this project. Consult them | ||
| via the Skill tool when their triggers match: | ||
|
|
||
| - `spacecraft-standard-constitution` — master Steelbore Standard | ||
| - `spacecraft-cli-standard` — structural CLI Standard rules | ||
| - `spacecraft-agentic-cli` — agent-facing UX for the CLI | ||
| - `spacecraft-brand-guidelines` — brand look-and-feel | ||
| - `steelbore-color-palette` — canonical palette values (§11) | ||
| - `microsoft-rust-guidelines` — Microsoft Pragmatic Rust Guidelines | ||
| - `spacecraft-cli-preference` — preferred external CLI tools (rg, fd, bat) | ||
| - `spacecraft-cli-shell` — shell syntax for generated commands | ||
| - <ADD-PROJECT-SPECIFIC-SKILLS> | ||
|
|
||
| ## MCP servers expected | ||
|
|
||
| - `<TOOL_NAME> mcp` — this project's own MCP surface (when implemented) | ||
| - <ADD-PROJECT-SPECIFIC-MCP-SERVERS> | ||
|
|
||
| ## Claude Code specifics | ||
|
|
||
| - <Slash commands this repo installs, `.claude/` layout, plan-mode notes, | ||
| subagent conventions, TaskMaster wiring — anything meaningless to Codex, | ||
| Cursor, or Goose.> | ||
| - <ADD-PROJECT-SPECIFIC-CLAUDE-NOTES> | ||
|
|
||
| <!-- | ||
| Tool preferences, commit-message format, and TODO conventions are NOT | ||
| Claude-only — they belong in AGENTS.md. Likewise CLAUDECODE=1 detection: | ||
| a CLI that checks it alongside CURSOR_AGENT and GEMINI_CLI is documenting | ||
| its own behavior, which every harness needs to know. | ||
| --> |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -25,8 +25,8 @@ does NOT belong, and provides anti-pattern catalogs. | |
|
|
||
| | File | Reader | Lifetime | Authoritative on | | ||
| |------|--------|----------|------------------| | ||
| | `AGENTS.md` | **Every** agent, Claude included (via the import below) | Loaded each session | **Authoritative.** Coding conventions, build/test commands, project invariants | | ||
| | `CLAUDE.md` | Claude Code | Loaded each session | An `@AGENTS.md` import plus Claude-only tool/skill/MCP context — nothing else | | ||
| | `SKILL.md` | Spacecraft Software Skills, CLI-Anything, `gws`-style skill systems | Loaded by skill loader | The CLI's own capability surface and triggering description | | ||
| | `CONTRIBUTING.md` | Human contributors | Read once during onboarding | Dev environment setup, PR conventions | | ||
|
|
||
|
|
@@ -123,13 +123,29 @@ Cargo workspace. It targets POSIX shell environments first and PowerShell | |
|
|
||
| ## §3 — CLAUDE.md: how it differs from AGENTS.md | ||
|
|
||
| **Standard §5.7 governs this file.** CLAUDE.md is an `@AGENTS.md` import | ||
| plus Claude-only content — it MUST NOT restate, summarize, or mirror | ||
| AGENTS.md. Copying or symlinking AGENTS.md into it is non-compliant: the | ||
| two copies are edited in different sessions, drift, and the agent reading | ||
| the stale one is never told it is stale. | ||
|
|
||
| > **This rule was inverted at Standard v1.46.** Earlier revisions of this | ||
| > reference told authors to make CLAUDE.md a strict superset by symlinking | ||
| > or copying. That produced duplication by construction. If you find a | ||
| > project still arranged that way, or a file carrying a "keep these two in | ||
| > sync" instruction, that instruction is the bug — fold the content into | ||
| > AGENTS.md and reduce CLAUDE.md to the shape below. | ||
|
|
||
| Anything that is true of the *project* goes in AGENTS.md. Only what a | ||
| non-Claude harness cannot act on belongs here: | ||
|
Comment on lines
+139
to
+140
There was a problem hiding this comment.
When authors follow this canonical example, the subsequent AGENTS.md reference: AGENTS.md:L434-L436 Useful? React with 👍 / 👎. |
||
|
|
||
| ```markdown | ||
| # CLAUDE.md — <project-name> | ||
|
|
||
| @AGENTS.md | ||
|
|
||
| > Record project knowledge in `AGENTS.md`, not here. This file holds | ||
| > only Claude-Code-only context. | ||
|
|
||
| ## Skills referenced | ||
| - `spacecraft-standard-constitution` — master Standard | ||
|
|
@@ -158,6 +174,27 @@ The Claude-specific sections matter because Claude Code has features | |
| Mentioning them in AGENTS.md would mislead a Codex CLI session into | ||
| expecting capabilities it doesn't have. | ||
|
|
||
| **The test for where a fact belongs:** would a Codex CLI or Cursor session | ||
| be worse off without it? If yes, it goes in AGENTS.md. `CLAUDECODE=1` is | ||
| the classic false positive — a CLI that detects it alongside `CURSOR_AGENT` | ||
| and `GEMINI_CLI` is documenting its own product behavior, which every | ||
| harness needs to know, so it belongs in AGENTS.md. | ||
|
|
||
| **CLAUDE.md is mandatory, even when it holds nothing else.** Claude Code | ||
| reads `CLAUDE.md`, not `AGENTS.md` — a project with only an AGENTS.md | ||
| gives a Claude session *no* project context at all. When there is nothing | ||
| Claude-only to say, the file is still four lines: the heading, the | ||
| `@AGENTS.md` import, and the blockquote. | ||
|
|
||
| Both files are tracked (§5.7). Neither may be gitignored: an ignored | ||
| AGENTS.md makes the import dangle on a fresh clone. Because they are | ||
| published artifacts, keep credentials, private hostnames, and personal | ||
| filesystem paths out of both — and review a previously-ignored context | ||
| file for sensitive content *before* un-ignoring it. | ||
|
|
||
| Tooling that renders managed blocks into context files (rule | ||
| synchronizers, task systems) targets AGENTS.md only. | ||
|
|
||
| --- | ||
|
|
||
| ## §4 — SKILL.md: the CLI's own skill manifest | ||
|
|
@@ -295,7 +332,7 @@ are inline in `#[cfg(test)] mod tests {}` blocks." | |
| | File | Target length | Hard cap | | ||
| |------|---------------|----------| | ||
| | AGENTS.md | 80–200 lines | 400 lines | | ||
| | CLAUDE.md | 5–40 lines | 80 lines | | ||
| | SKILL.md | 50–150 lines | 300 lines | | ||
| | CONTRIBUTING.md | (no agent-loaded budget) | — | | ||
|
|
||
|
|
||
Oops, something went wrong.
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For users who install
spacecraft-agentic-cli.zipor.skill, both unchanged bundles still contain the old guidance thatCLAUDE.mdshould duplicateAGENTS.md; they also omit all four updated source/reference/template files in this commit. Rebuild and commit both bundles so the install surface actually delivers the policy introduced here.AGENTS.md reference: AGENTS.md:L406-L409
Useful? React with 👍 / 👎.