project-structure

---
name: project-structure
description:
  Mandatory practices for reading, understanding, and maintaining project
  documentation (CLAUDE.md, ARCHITECTURE.md). This skill MUST be used for ALL
  coding tasks, ALL conversations, ALL projects, regardless of language or
  context. It defines non-negotiable rules for how to orient yourself in any
  codebase before doing any work. Trigger on every single interaction — any file
  edit, code review, bug fix, feature addition, refactoring, question about
  code, or any task that involves a project directory. There are no exceptions.
  Even if the user asks a simple question, these rules apply.
---

## Reading Project Documentation

- Before doing ANY work in a project, read all CLAUDE.md files in the hierarchy
  — from the current working directory up through every parent directory to the
  project root. These files tell you where you are, what the project is, and how
  to work on the code. They contain critical guidance, conventions, and rules
  specific to that project and its modules.
- NEVER skip reading these files. No matter what. No matter how small the task
  seems. No matter if you think you already know the answer. Read them every
  time.

### ARCHITECTURE.md

- If there is an ARCHITECTURE.md file next to the closest (most specific)
  CLAUDE.md, always read it too. It contains system design, module boundaries,
  data flows, and key decisions that you need to understand.
- You don't need to read ARCHITECTURE.md files next to parent CLAUDE.md files
  unless you feel the task requires that broader architectural context.

## Maintaining Project Documentation

- Update CLAUDE.md IMMEDIATELY when you learn new things about the project.
  NEVER ask for permission — just do it. This includes things you learn from:
  - Reading code and discovering patterns or conventions
  - User corrections or preferences during conversation
  - Build/test commands and workflows
  - Module responsibilities and boundaries
  - Gotchas, edge cases, or non-obvious behaviors
- Apply common sense about where to put what:
  - If the learning is specific to a library or crate, update or create the
    CLAUDE.md at that library/crate root.
  - If the learning is generic and applies to the whole project, update the root
    CLAUDE.md.

### Ensuring CLAUDE.md Coverage

- Every Cargo.toml and package.json must have a sibling CLAUDE.md. If one
  doesn't exist, create it. It's fine to start with an empty file and fill it as
  you learn about that package. This applies to every crate and package in a
  workspace — the root and every member.

More agent context in enso-org/enso

13 other files this repository gives its agents.