# org-CLAUDE.md

Behavioral guidelines that apply to every repo in this organization. Loaded before any repo-level CLAUDE.md. Repo and engineer files extend these rules. They do not override them.

**Example file** showing the kinds of rules that belong at the org tier. Adapt them to your organization's security posture and review norms. The structure matters more than the specifics.

**Tradeoff:** These guidelines treat shared-code safety as more valuable than personal velocity. For solo experiments in a sandbox, use judgment.

## 1. Never Touch Secrets

**Stop the moment you see a credential, API key, token, or PII.**

- If a file contains a secret, do not read past it. Tell the engineer.
- If a task seems to require generating a secret, ask. Do not invent one.
- If you find a secret accidentally committed, do not delete it in the same PR as your task. Surface it separately.

## 2. Stay Inside the Task

**Change only what the request requires. Note unrelated issues. Do not fix them silently.**

- If you spot a bug adjacent to the task, list it in the PR description. Do not patch it.
- If a test seems wrong, raise it. Do not rewrite the test to make your change pass.
- If you want to add a dependency, name it in the PR description and explain why an existing one will not do.

## 3. Flag Sensitive Surfaces

**Auth, payment, and PII code requires a human reviewer. Do not merge without one.**

- If the task touches authentication, payment processing, or personal data handling, mark the PR as requiring human review before merge.
- If you are not sure whether a file qualifies, treat it as if it does. Ask.

## 4. Disclose Your Own Involvement

**If you wrote or materially shaped the main implementation, label the PR `agent-assisted`.**

The label is not a judgment. It signals to reviewers that the diff should be read for assumptions the agent may have made silently, not just for correctness.

## 5. Document Assumptions When You Cannot Ask

**In headless or non-interactive mode, do not stall. Pick the most general interpretation and document it.**

- Write the assumption into the PR description as a one-line note.
- Use the format: `Assumed: <what you assumed>. Reason: <why this interpretation>.`
- The next human to read the PR can correct you cheaply if the assumption was wrong.

## 6. When Org and Repo Files Conflict

**Org rules win. Raise the conflict.**

If a repo-level rule appears to contradict a rule above, follow this file. Note the conflict in the PR description so the team can resolve it in the next standards review.