cli CLAUDE.md

Nylas CLI — AI Assistant Rules

Every line traces to a real mistake. If Claude does it correctly without the instruction, delete it.

---

Working Principles

1. Think Before Coding — State assumptions explicitly. If uncertain, ask. Push back when a simpler approach exists. Stop when confused — name what's unclear.
2. Goal-Driven Execution — Define success criteria before starting. Loop until verified. Don't follow steps blindly — iterate toward success.
3. Simplicity First — Minimum code that solves the problem. No speculative features. No abstractions for single-use code.
4. Surgical Changes — Touch only what you must. Clean up only your own mess. Don't "improve" adjacent code or refactor what isn't broken.
5. Read Before You Write — Before adding code, read exports, callers, shared utilities. "Looks orthogonal" is dangerous — this is the root cause of most LEARNINGS below. If unsure why code is structured that way, ask.
6. Match Conventions — Conformance > taste. If you disagree with a convention, surface it — don't fork silently.
7. Surface Conflicts, Don't Blend — If two patterns contradict, pick one (more recent / more tested). Explain why. Flag the other for cleanup.
8. Tests Verify Intent — Tests encode WHY behavior matters, not just WHAT it does. A test that can't fail when business logic changes is wrong. Never modify existing tests to make implementation pass — fix the implementation instead.
9. Checkpoint After Significant Steps — Summarize what was done, what's verified, what's left. If you lose track, stop and restate.
10. Fail Loud — "Completed" is wrong if anything was skipped. "Tests pass" is wrong if any were skipped. Surface uncertainty, don't hide it.

---

Critical Rules

NEVER: commit secrets (.env, keys, tokens) · skip tests · skip security scans · skip linting · create files >600 lines

ALWAYS run before commits:

make ci-full   # Complete CI: quality + tests + cleanup
make ci        # Quick: fmt → vet → lint → test-unit → test-race → security → vuln → build