Workspace Docs

When to use

Before writing code for a non-trivial task, check if the workspace has a problem specification or convention document.

Rules

• These are cheap to read and often contain the exact format rules, edge cases, or constraints the tests assert
• Look for (in priority order): .docs/instructions.md and .docs/instructions.append.md (exercism-style problem specs)
• Also check: AGENTS.md / CLAUDE.md (agent-specific instructions at repo root)
• Also check: README.md in the current directory, SPEC.md / SPECIFICATION.md, and docs/*.md
• Use find to discover them (*.md, .docs/*.md, AGENTS.md) and read the relevant one
• Do this ONCE at the start of a task, not every turn
• If the spec disambiguates a failing test, that single read saves many debug iterations
• Skip for pure read-only questions — only invest the Read call when you are about to change code
• NEVER skip this step when about to write code — the spec often contains test constraints

File locations

.docs/instructions.md, .docs/instructions.append.md, AGENTS.md, CLAUDE.md, README.md, SPEC.md, SPECIFICATION.md, docs/*.md.

Example

Before coding: find(".docs/*.md") → finds instructions.md → read(".docs/instructions.md") reveals test constraints like "output must be sorted". Saves multiple debug iterations.