feat: Add Colin's set of claude settings and my settings

2026-08-11 13:20:42 -07:00
parent 6076a4f3bf
commit d74358e366
11 changed files with 342 additions and 0 deletions
@@ -0,0 +1,45 @@
+Use `jj` instead of `git` or `gt` for all version control operations.
+
+Custom revsets:
+- `stack` represents all the commits in the current stack (works even when the current commit is an empty child created by `jj new`)
+
+Other key commands:
+- `jj squash --from <id> --into <id> -- <paths>` to move whole files between commits
+- `jj split -r <id> -m <message> -- <paths>` to split a commit (selected files stay, rest go to new child)
+- `jj describe <id> -m <message>` to rename a commit
+- `jj diff -r <id> -- <path>` to see a specific file's diff in a commit
+- `jj diff -r <id> --name-only` to list changed files
+- `jj log -r stack` to see the current stack (stack is a custom revset described above)
+
+Rebasing and conflicts:
+- jj automatically rebases descendants when editing earlier commits. Expect cascading conflicts after modifying earlier commits, and resolve them working down the stack.
+- Use the `new`, ..., `squash` sequence when resolving conflicts.
+
+Things to avoid:
+- Avoid `jj absorb` -- in a complex stack, it's likely to lose changes or put things into the wrong commits.
+- Avoid `jj edit <id>` -- always prefer to open a new commit (`jj new <id>`) first.
+
+## Editing files
+
+**Before editing any files, always consider which new or existing commit the edits should be part of!**
+
+Edits should always be made in a new commit, and then squashed once they are finalized:
+- `jj new <id>` to open a new child of an existing commit
+- make the changes
+- `jj squash --into <id> --use-destination-message` to squash into the existing commit
+
+If the intent is to *add* a new commit rather than edit an existing one:
+- use `jj new <id>` where <id> is the top commit of the stack
+- or use `jj new --insert-before <id>` or `jj new --insert-after <id>` to insert a new commit mid-stack
+
+When squashing or splitting, make sure that bookmarks stay attached to their original commits (because bookmarks map to PRs).
+
+## Pushing changes to GitHub/Graphite
+
+Verify the stack first: Before pushing changes, always verify that there are no lingering temporary commits included in the `stack` revset. New commits that were intentionally introduced (intended to become new PRs) are fine. If there are lingering temporary commits, **do not push**; either resolve or get help from the user.
+
+After verifying the stack:
+- If the repo uses Graphite: use `jfd` to push to Graphite. This submits all commits in the `stack` revset as a 1:1 mapping of PRs to commits.
+- If the repo does not use Graphite: use `jj git push -c stack` to push all commits in the stack (this creates an automatically-named branch for each commit). Then use `gh` to create a PR for each branch.
+
+To push a fresh commit (e.g. to retrigger CI), use `jj metaedit --force-rewrite <id>` to get a fresh commit hash, then push normally.
@@ -0,0 +1,39 @@
+# PR Titles
+
+Sample PR title: `[SG-100] [wip] api: Move feature-flags into a separate package`
+
+1. Linked ticket number, if the ticket is known. If the ticket isn't known, just omit the ticket number. Never ask the user for ticket numbers. There is a separate automated process that will add a ticket number later. The `check` CI job will fail on the missing ticket until this automation runs; treat that specific failure as expected and self-resolving, not something to fix.
+2. Work-in-progress tag — this indicates that the PR shouldn't be reviewed yet because some part of it is incomplete.
+3. Commit title (using standard Git conventions)
+
+# Draft status
+
+Always create PRs as drafts. Never automatically move PRs out of draft status. Nicholas will promote PRs out of draft status when he is ready for them to be reviewed by others.
+
+# PR Descriptions
+
+PR descriptions always follow this template:
+
+```
+## Overview
+
+[overview here]
+
+## Customer visible changes
+
+N/A
+
+## How did you test these changes?
+
+[testing steps here]
+```
+
+The default template that Graphite uses for new PRs should be ignored entirely — don't keep the placeholders or the checkboxes in the testing section.
+
+## Overview
+The overview should be terse and should not explain implementation details except at a *very* high level (anything lower level should be omitted because it can be determined by looking at the code itself). The two main audiences are (1) reviewers and (2) future engineers who are debugging issues. The primary goal is to explain the *why* of the change. What's the goal/benefit? What bug is being fixed? If there were several obvious ways it could be done, why did we choose this specific way?
+
+If there are known deficiencies in the current verison of the PR, they should be listed as "TODO: ..." at the end of the Overview.
+
+## How did you test
+The testing steps should be concise but precise. "All changes are covered by unit tests" can be sufficient if it's true. If manual steps were performed to verify that the changes work, those steps should be listed explicitly (a numbered list with a single sentence per number is ideal). If the author needs to perform manual verification steps before merging the PR, they should be listed here as "TODO: ...".
@@ -0,0 +1,10 @@
+Always identify yourself explicitly as Claude when writing things that will appear with the user's identity:
+- PR titles: No identification required — the "Co-Authored-By" line in the commit message is sufficient.
+- PR comments: Start the comment with "[claude]:"
+- Linear tickets: Start the description with "[claude]:"
+- Linear comments: Start the comment with "[claude]:"
+- Commit messages: End the commit message with "Co-Authored-By: [model]"
+
+When you are acting on direct instruction from the user, include that as justification (e.g. "[claude]: closing this at Nicholas's request").
+
+Don't nitpick errors in other people's comments when the intent is clear. For example, if someone says "use the shared function `sortThings` for this", and it turns out the function is actually called `sortThingsAscending`, don't correct them; just use the correct function and respond as if they hadn't made the error. One exception to this is comments made by the invoking user: *Do* nitpick that user's comments.