Skip to content

Add CLAUDE.md as minimal pointer to AGENTS.md #52

@dgenio

Description

@dgenio

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

  • documentation
  • priority:P2
  • ai-friendly
  • milestone:v0.1.0

Depends on

Acceptance criteria

  • CLAUDE.md exists 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

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions