-
Notifications
You must be signed in to change notification settings - Fork 0
Open
Labels
ai-friendlydocumentationImprovements or additions to documentationImprovements or additions to documentationmilestone:v0.1.0priority:P2
Description
Why
Claude Code reads CLAUDE.md at the repo root as its primary project context file. Without one, Claude-based agents receive no project-specific guidance. However, we already have a comprehensive AGENTS.md (see #51) that covers everything — duplicating that content in CLAUDE.md would create drift risk.
Best practice: CLAUDE.md should be a minimal pointer to AGENTS.md, not a copy.
Scope / Proposed changes
Create a single file:
CLAUDE.md(repository root, ≤15 lines)
Proposed contents
# CLAUDE.md — ChainWeaver
This file is the entry point for Claude Code. All project context, architecture details,
coding conventions, and guardrails are maintained in a single canonical source:
→ **Read [AGENTS.md](AGENTS.md) before making any changes.**
## Quick invariants (also in AGENTS.md § Top invariants)
1. No LLM calls in `executor.py` — deterministic by design.
2. All exceptions inherit from `ChainWeaverError`.
3. All public symbols exported in `__init__.py` `__all__`.
4. `from __future__ import annotations` at the top of every module.
5. All code must pass: `pytest`, `ruff check`, `ruff format --check`.The quick invariants are the only content allowed to be duplicated from AGENTS.md. They are intentionally kept to ≤5 items (a curated subset of the full ≤10 in AGENTS.md) for fast context loading.
Labels to apply
documentationpriority:P2ai-friendlymilestone:v0.1.0
Depends on
- Add AGENTS.md with architecture map, decision context, and agent guardrails #51 — AGENTS.md must exist first (CLAUDE.md points to it)
Acceptance criteria
-
CLAUDE.mdexists at repository root - File is ≤15 lines
- File contains a link to
AGENTS.md - Invariants listed are a subset of those in AGENTS.md (no unique content)
- No architecture map, decision context, or procedures duplicated from AGENTS.md
Avoid drift/duplication notes
- CLAUDE.md is read-only in spirit — its content derives entirely from AGENTS.md.
- When AGENTS.md invariants change, the subset in CLAUDE.md must be updated in the same PR.
- If CLAUDE.md grows beyond 15 lines, it's a smell — context belongs in AGENTS.md.
References
- Claude Code: CLAUDE.md support
- Add AGENTS.md with architecture map, decision context, and agent guardrails #51 — AGENTS.md (parent context file)
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
ai-friendlydocumentationImprovements or additions to documentationImprovements or additions to documentationmilestone:v0.1.0priority:P2