diff --git a/CLAUDE.md b/CLAUDE.md index f733ac9..c758687 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,19 +4,12 @@ When doing repo operations, always use the global install of `atgc` (not the one ## Feature branch workflow -Some points to keep in mind: +If asked to do work, unless directly instructed otherwise, do not make changes to the user's top-level git checkout (other than making worktrees attached to it). All of your work will be on feature branches. -- If asked to do work, unless directly instructed otherwise, do not make changes to the user's top-level git checkout (other than making subtrees attached to it). -- While doing work, you are one of many agents running on a system: - - Do not restart, reload, or otherwise modify the configuration of shared services. - - If you need temporary folders or other artifacts that exist outside your worktree (such as Docker images), reduce conflicts by tagging them with your current branch and/or SHA. - - Check available system resources before running expensive commands (memory or CPU). -- All code will be human-reviewed. All commentary about feature implementation should be concise, avoid flowery or verbose language, and focus on what the change accomplishes. - -Before starting work on a feature: +To start work on a feature branch: - Create a new branch like "claude/short-feature-name", based on `origin/main` -- Create a worktree in `.claude/worktrees` for working on the feature branch +- Create a git worktree in `.claude/worktrees` for working on the feature branch - Enter the worktree so that all commands run inside of it - Double check that the repo-local `.git/config` `[user]` section has an ATProto `@-` handle as a `name` and its `did:plc` as an email @@ -26,7 +19,7 @@ Each feature branch should include supporting work: - Adding new debug log lines or similar observability - An update to any high-level documentation (if needed) - A few of high-value tests (if applicable) -- Checking off completed issues in TODO.md +- Checking off completed work in TODO.md Structure your commits: @@ -34,9 +27,15 @@ Structure your commits: - Use Conventional Commits, including adding "!" indicators for breaking behavior changes. - Don't write more than 1 short sentence + 1 short paragraph into a commit body. +While doing work, respect other agents running on the system: + +- Do not restart, reload, or otherwise modify the configuration of shared services. +- If you need temporary folders or other artifacts that exist outside your worktree (such as Docker images), reduce conflicts by tagging them with your current branch and/or SHA. +- Check available system resources before running expensive commands (memory or CPU). + Before submitting a PR: -- Check for a rebase against `origin/main` and fix any conflicts +- Check for new commits on `origin/main`. Rebase and fix any conflicts - Ensure that all `prek` feedback has been fixed - Ensure that relevant tests pass @@ -44,12 +43,13 @@ When writing any PRs, updates to PRs, or comments on PRs: - The PR title should be simple and descriptive, and should use Conventional Commits. - The PR body should contain a before/after screenshot if the change has a visible effect (UI, rendered output, a CLI's printed text). Attach this with Markdown image syntax and a local image path: the `atgc` commands will upload it for you. +- All code will be human-reviewed. All commentary about feature implementation should be concise, avoid flowery or verbose language, and focus on what the change accomplishes. -To submit a PR: +When your work is ready for review, submit a PR. Do not claim your work is "done" without following these steps: -- Push the rebased branch to the origin. Tangled uses patch-based rounds, so pushing a remote and submitting a PR are different operations. -- If the PR is a handful of commits, submit it via `atgc pr create` -- If the PR would be more than a handful of commits, prefer `atgc stack create` to break it into reviewable PRs for logical sub-features. `atgc stack resubmit` reconciles the chain after a rebase or reorder. +- Push the feature branch to the origin. Tangled uses patch-based rounds, so pushing a remote and submitting a PR are different operations. +- If the PR is a handful of commits with no subfeatures expected, submit the change via `atgc pr create` +- If the PR would be more than a handful of commits or will be followed up by additional feature PRs with a dependency order, prefer `atgc stack create` to break the change into logical sequences of reviewable PRs, each with their own preview images. - When the PR has been created, post the Tangled PR link for the user to review. If asked to iterate post-submission, each iteration should: