From e1bac5b228d7eb4025e364b57c1ce188e6fd0a56 Mon Sep 17 00:00:00 2001 From: nkoji21 <133028205+nkoji21@users.noreply.github.com> Date: Mon, 15 Jun 2026 14:16:48 +0900 Subject: [PATCH 1/5] =?UTF-8?q?feat(git-commit):=20revertability=E9=87=8D?= =?UTF-8?q?=E8=A6=96=E3=81=AE=E5=93=B2=E5=AD=A6=E3=81=A8references/?= =?UTF-8?q?=E3=82=92=E8=BF=BD=E5=8A=A0=E3=81=97=E3=82=A8=E3=83=BC=E3=82=B8?= =?UTF-8?q?=E3=82=A7=E3=83=B3=E3=83=88=E5=9B=BA=E6=9C=89=E3=83=95=E3=83=83?= =?UTF-8?q?=E3=82=BF=E3=83=BC=E3=82=92=E5=BB=83=E6=AD=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ryoppippiのcommitスキルからrevertable-commits/git-apply/pushの詳細をreferences/に分離し本体を薄く保つ。共有スキルのためCo-Authored-By等のエージェント識別フッターは付けない方針に変更。 --- .agents/skills/git-commit/SKILL.md | 84 ++++++++++++++----- .../skills/git-commit/references/git-apply.md | 61 ++++++++++++++ .agents/skills/git-commit/references/push.md | 37 ++++++++ .../references/revertable-commits.md | 62 ++++++++++++++ 4 files changed, 225 insertions(+), 19 deletions(-) create mode 100644 .agents/skills/git-commit/references/git-apply.md create mode 100644 .agents/skills/git-commit/references/push.md create mode 100644 .agents/skills/git-commit/references/revertable-commits.md diff --git a/.agents/skills/git-commit/SKILL.md b/.agents/skills/git-commit/SKILL.md index 7999417..db68183 100644 --- a/.agents/skills/git-commit/SKILL.md +++ b/.agents/skills/git-commit/SKILL.md @@ -5,7 +5,8 @@ user-invocable: true allowed-tools: Bash --- -Review current changes and autonomously commit following Conventional Commits. +Review current changes and autonomously create fine-grained, independently +revertable commits following Conventional Commits. **Working tree status (source repo):** ``` @@ -19,28 +20,48 @@ Review current changes and autonomously commit following Conventional Commits. ## Arguments -If a `--path ` argument is provided (e.g. invoked as `git-commit --path /tmp/feat-foo`), all git commands must be run inside that directory by prepending `cd &&` to every Bash command. This overrides the current working directory. - -1. Run `git status`, `git diff`, and `git log --oneline -5` to understand the changes and context -2. Decide the commit message autonomously -3. Stage and commit using `git apply` (see below) - -## Principle -- Write **Why** in the subject line itself — keep it concise but meaningful. -- Body is optional. If you feel a body is necessary, the commit is likely too large — consider splitting it. -- Footer (Co-Authored-By) is always required. -- Each commit must be **independently revertable** without breaking other functionality. +- `--path `: run every git command inside `` by prepending `cd &&` + to each Bash command. This overrides the current working directory (e.g. invoked + as `git-commit --path /tmp/feat-foo`). +- `--push`: push to remote after all commits are complete (default: off). See the + **Push** section below. + +1. Run `git status`, `git diff HEAD`, and `git log --oneline -10` to understand the + changes and context +2. Decide commit boundaries and messages autonomously +3. Stage and commit each unit using `git apply --cached` (see below) + +## Core Philosophy — Revertability First + +Each commit must be **revertable independently** without breaking other +functionality. Prefer smaller, granular commits over large groupings — split by +hunks within files, not just whole files. + +- **Tiny commits are expected.** A single review comment, one wording correction, + one reference-file extraction, one symlink sync, or one formatting pass can each + be its own commit when independently revertable. PR branches are squash-merged + later, so don't worry about granularity being too fine. +- **Tiny does not mean incomplete.** For moves, renames, or extractions, one commit + must include *both* sides: remove/update the old location, add the new location, + update references, and sync generated links. Never commit only the destination of + a move while leaving the source/reference cleanup for later. +- **Don't `--amend` away review history.** PR branches are squash-merged, so keep + review fixes as small follow-up commits that can be reverted independently. Amend + only for unpublished local mistakes or when the user explicitly asks. + +For concrete good and bad examples, read `references/revertable-commits.md`. ## Commit Granularity - 1 commit = 1 logical change - Examine individual hunks, not entire files — split if needed - Separate refactoring and feature additions - Tests can be in the same commit as the main code -- Formatting-only changes should be separate +- Formatting-only changes should be separate (`chore(xxx): format` or `chore: format`) ## Staging with git apply -Never use interactive commands like `git add -p`. Instead: +Never use interactive commands like `git add -p` or `git add --interactive` — +Claude Code cannot handle them. Instead: ```bash # 1. Generate patch for the target changes @@ -53,11 +74,16 @@ git apply --cached --check patch.diff git apply --cached patch.diff ``` +When a patch fails, needs whitespace handling, or must be staged without touching +unrelated hunks, read `references/git-apply.md`. + ## Commit Message Format Conventional Commits v1.0.0 Format: `type(scope): description` -- scope: optional (e.g., `alacritty`, `vim`, `git`) +- **type**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, + `ci`, `chore`, `revert` +- **scope**: optional (e.g., `alacritty`, `vim`, `git`) - **description: in English** — convey Why, not just What, but keep it short Examples: @@ -69,7 +95,27 @@ fix(git): remove deprecated option fix(git): remove deprecated option to prevent startup warning ``` -Required footer: -``` -Co-Authored-By: Claude -``` +Body is optional. If you feel a body is necessary, the commit is likely too large — +consider splitting it. + +Do not add a `Co-Authored-By` or any agent-identifying footer. This skill is shared +across Claude / Codex / Cursor, so hardcoding a single agent name would mislabel +commits made by the others. + +## Quality Checks +- Can this be reverted without breaking other functionality? +- Is this the smallest logical unit? +- Does the message clearly explain the change (Why)? +- Does it match the project's commit patterns, scopes, and style? +- No debugging statements or commented-out code without explanation + +## Push (only if `--push`) + +After all commits are complete, push to remote. Let repository git hooks run; if a +pre-commit or pre-push hook runs format, sync, lint, typecheck, or tests, treat +those as part of the normal validation path and fix any failures in a new small +commit. + +Never push to `main`/`master` directly — create a feature branch first. + +Read `references/push.md` for the exact branch/upstream checks and push commands. diff --git a/.agents/skills/git-commit/references/git-apply.md b/.agents/skills/git-commit/references/git-apply.md new file mode 100644 index 0000000..9032ef6 --- /dev/null +++ b/.agents/skills/git-commit/references/git-apply.md @@ -0,0 +1,61 @@ +# Git Apply Reference + +## Basic Usage + +```bash +# Always verify first before applying +git apply --check patch_file.patch + +# Apply with verbose output for debugging +git apply -v patch_file.patch + +# Stage without touching the worktree +git apply --cached -v patch_file.patch + +# Apply a diff generated between refs +git diff main...HEAD -- | git apply -v +``` + +## Essential Flags + +- `-v, --verbose`: always use this for detailed feedback during application. +- `--check`: verify whether a patch can be applied cleanly without making changes. +- `--cached`: stage the patch without applying it to the worktree. +- `--stat`: display affected files before applying. +- `--whitespace=fix`: automatically correct trailing whitespace issues. +- `--reject`: create `.rej` files for failed sections instead of aborting entirely. +- `--reverse` / `-R`: revert a previously applied patch. + +## Troubleshooting Failed Applies + +Trailing whitespace: + +```bash +git apply --check --whitespace=fix patch_file.patch +git apply --whitespace=fix -v patch_file.patch +``` + +Partial failures: + +```bash +git apply --reject -v patch_file.patch +``` + +Context mismatch: + +```bash +git apply --ignore-whitespace -v patch_file.patch +``` + +Line ending issues: + +```bash +git apply --ignore-space-change -v patch_file.patch +``` + +## Git Apply vs Git Am + +- `git apply`: applies or stages changes without creating commits. +- `git am`: applies patches with commit messages and author info preserved. + +Use `git apply -v` for this workflow to keep commit creation explicit and controlled. diff --git a/.agents/skills/git-commit/references/push.md b/.agents/skills/git-commit/references/push.md new file mode 100644 index 0000000..24184f4 --- /dev/null +++ b/.agents/skills/git-commit/references/push.md @@ -0,0 +1,37 @@ +# Push Reference + +Run in `sh`/`zsh` (this repo's shell). Do NOT use fish syntax. + +## 1. Check the current branch before any push + +```bash +current_branch=$(git branch --show-current) +if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then + echo "On $current_branch — stop. Create a feature branch before pushing." +fi +``` + +If the current branch is `main` or `master`, stop and create a feature branch +before pushing. + +## 2. Check if the branch has an upstream + +```bash +git rev-parse --abbrev-ref --symbolic-full-name '@{u}' +``` + +- **If this succeeds** (an upstream exists), push directly: + + ```bash + git push + ``` + +- **If this fails** (no upstream), ask the user whether to set upstream and push: + - If yes: `git push -u origin HEAD` + - If no: skip pushing. + +## 3. Hooks + +Let repository git hooks run. If a pre-push hook runs format, sync, lint, +typecheck, or tests and one fails, fix it in a new small commit and push again — +treat hook failures as part of the normal validation path, not as errors to bypass. diff --git a/.agents/skills/git-commit/references/revertable-commits.md b/.agents/skills/git-commit/references/revertable-commits.md new file mode 100644 index 0000000..538221b --- /dev/null +++ b/.agents/skills/git-commit/references/revertable-commits.md @@ -0,0 +1,62 @@ +# Revertable Commit Examples + +## Good: split independent implementation steps + +```text +feat(auth): add RefreshTokenService class + +Added RefreshTokenService to handle token lifecycle management. +This service generates and invalidates refresh tokens with +configurable expiry periods. +``` + +```text +feat(auth): integrate token rotation in middleware + +Updated auth middleware to call RefreshTokenService when validating +tokens. This can be reverted independently without removing the +service itself. +``` + +## Good: keep both sides of a move together + +One commit contains: + +- `A .agents/skills/tdd/references/vitest-examples.md` +- `M .agents/skills/tdd/SKILL.md` +- `D .agents/skills/tdd/vitest-example.md` + +The commit is still small, but it is complete: the old path is removed, the new +path is added, and every reference points to the new path. + +## Bad: split one move across incomplete commits + +First commit: + +- `A .agents/skills/tdd/references/vitest-examples.md` + +Second commit: + +- `M .agents/skills/tdd/SKILL.md` +- `D .agents/skills/tdd/vitest-example.md` + +The first commit is not independently revertable because it leaves duplicate or +unreachable guidance until the second commit lands. + +## Good: one review comment per commit + +If a reviewer says "run format before typecheck/test", one commit can update only +that workflow wording and the matching always-on reminder. Keep unrelated examples, +source docs, and typo fixes for separate commits. + +## Bad: tidy broad commit + +Avoid a commit that mixes: + +- PR review workflow changes +- TypeScript assertion guidance +- OpenCode data-source corrections +- Markdown fence formatting +- Generated symlink sync + +Even if each change is correct, reverting one concern would revert unrelated work. From b9c2065cdfe0232e6c648f82fcb42dc58f9ccaff Mon Sep 17 00:00:00 2001 From: nkoji21 <133028205+nkoji21@users.noreply.github.com> Date: Mon, 15 Jun 2026 14:16:58 +0900 Subject: [PATCH 2/5] =?UTF-8?q?feat(git-commit-ja):=20=E5=A7=94=E8=AD=B2?= =?UTF-8?q?=E5=85=88=E3=81=AE=E8=8B=B1=E8=AA=9E=E6=8C=87=E7=A4=BA=E3=81=A8?= =?UTF-8?q?=E3=81=AE=E8=A1=9D=E7=AA=81=E3=82=92=E9=98=B2=E3=81=90=E3=81=9F?= =?UTF-8?q?=E3=82=81=E8=A8=80=E8=AA=9E=E4=B8=8A=E6=9B=B8=E3=81=8D=E3=82=92?= =?UTF-8?q?=E6=98=8E=E7=A4=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 薄いラッパーだと/git-commitの英語/UKスペル指示と日本語指示が衝突し推論が揺れるため、type/scopeは英語・descriptionは日本語という言語ルールを委譲先より優先する旨を自己完結で明記。 --- .agents/skills/git-commit-ja/SKILL.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/.agents/skills/git-commit-ja/SKILL.md b/.agents/skills/git-commit-ja/SKILL.md index 92fd77e..3cf4de6 100644 --- a/.agents/skills/git-commit-ja/SKILL.md +++ b/.agents/skills/git-commit-ja/SKILL.md @@ -5,6 +5,23 @@ user-invocable: true allowed-tools: Bash, Skill --- -Use /git-commit to perform the commit, but write the commit message description **in Japanese**. +Use `/git-commit` to perform the commit (granularity, revertability, `git apply` +staging, and `references/` all apply unchanged). It also forwards any `--path` / +`--push` arguments. -Example: `fix(alacritty): 起動時警告を消すため非推奨オプションを削除` +## Language override (this skill takes precedence) + +`/git-commit` instructs English commit messages. When this skill runs, **the +following language rules override that** — re-confirm them right before writing each +message: + +- **type**: English Conventional Commits type (`feat`, `fix`, `docs`, `refactor`, + `chore`, …). +- **scope**: English (e.g. `alacritty`, `vim`, `git`). +- **description**: 日本語で書く。What だけでなく Why を簡潔に。 + +Example: + +``` +fix(alacritty): 起動時警告を消すため非推奨オプションを削除 +``` From 3dc208a9c461391595b0dae15ab4df61d4c8cff3 Mon Sep 17 00:00:00 2001 From: nkoji21 <133028205+nkoji21@users.noreply.github.com> Date: Mon, 15 Jun 2026 14:27:01 +0900 Subject: [PATCH 3/5] =?UTF-8?q?fix(git-commit):=20push.md=E3=81=AE?= =?UTF-8?q?=E3=83=96=E3=83=A9=E3=83=B3=E3=83=81=E3=82=AC=E3=83=BC=E3=83=89?= =?UTF-8?q?=E3=81=ABexit=E8=BF=BD=E5=8A=A0=E3=81=A8push=E6=99=82=E3=81=AE-?= =?UTF-8?q?-path=E4=BC=9D=E6=92=AD=E3=82=92=E6=98=8E=E8=A8=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit echoのみで停止せず保護ブランチにpushしうる不具合を修正。--push時にコマンドがフォールスルーして main/master へ push する事故を防ぐ。--path併用時のcd前置も明示。 --- .agents/skills/git-commit/references/push.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.agents/skills/git-commit/references/push.md b/.agents/skills/git-commit/references/push.md index 24184f4..08f67d6 100644 --- a/.agents/skills/git-commit/references/push.md +++ b/.agents/skills/git-commit/references/push.md @@ -2,17 +2,22 @@ Run in `sh`/`zsh` (this repo's shell). Do NOT use fish syntax. +When invoked with `--path `, prepend `cd &&` to every command below so +the push targets that repository, not the current working directory. + ## 1. Check the current branch before any push ```bash current_branch=$(git branch --show-current) if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then echo "On $current_branch — stop. Create a feature branch before pushing." + exit 1 fi ``` If the current branch is `main` or `master`, stop and create a feature branch -before pushing. +before pushing. The `exit 1` above guarantees execution halts instead of falling +through to the push step. ## 2. Check if the branch has an upstream From 068a3ed68bcb916308a49b6305f99cadd8ab8289 Mon Sep 17 00:00:00 2001 From: nkoji21 <133028205+nkoji21@users.noreply.github.com> Date: Mon, 15 Jun 2026 14:27:11 +0900 Subject: [PATCH 4/5] =?UTF-8?q?fix(git-commit):=20git-apply.md=E3=82=92sta?= =?UTF-8?q?ging=E5=89=8D=E6=8F=90=E3=81=AB=E7=B5=B1=E4=B8=80=E3=81=97conte?= =?UTF-8?q?xt=20mismatch=E3=82=92--3way=E3=81=AB=E8=A8=82=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 全例を--cached既定にしてworktree誤改変を防止。context mismatchに誤った--ignore-whitespaceではなく--3way/-Cを案内するよう訂正。 --- .../skills/git-commit/references/git-apply.md | 40 +++++++++++-------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/.agents/skills/git-commit/references/git-apply.md b/.agents/skills/git-commit/references/git-apply.md index 9032ef6..b0000e3 100644 --- a/.agents/skills/git-commit/references/git-apply.md +++ b/.agents/skills/git-commit/references/git-apply.md @@ -1,19 +1,20 @@ # Git Apply Reference +This skill stages patches **without touching the worktree**, so every command here +uses `--cached` by default. Drop `--cached` only when you deliberately want to apply +to the working tree instead of the index. + ## Basic Usage ```bash -# Always verify first before applying -git apply --check patch_file.patch - -# Apply with verbose output for debugging -git apply -v patch_file.patch +# Always verify first before staging (no changes on failure) +git apply --cached --check patch_file.patch -# Stage without touching the worktree +# Stage with verbose output for debugging git apply --cached -v patch_file.patch -# Apply a diff generated between refs -git diff main...HEAD -- | git apply -v +# Stage a diff generated between refs +git diff main...HEAD -- | git apply --cached -v ``` ## Essential Flags @@ -31,26 +32,32 @@ git diff main...HEAD -- | git apply -v Trailing whitespace: ```bash -git apply --check --whitespace=fix patch_file.patch -git apply --whitespace=fix -v patch_file.patch +git apply --cached --check --whitespace=fix patch_file.patch +git apply --cached --whitespace=fix -v patch_file.patch ``` -Partial failures: +Partial failures (write `.rej` files for the hunks that don't apply): ```bash -git apply --reject -v patch_file.patch +git apply --cached --reject -v patch_file.patch ``` -Context mismatch: +Context mismatch — the surrounding lines in the file no longer match the patch +context (line offsets / fuzz). Prefer a three-way merge, which uses the blob the +patch was based on: ```bash -git apply --ignore-whitespace -v patch_file.patch +git apply --cached --3way -v patch_file.patch ``` +If `--3way` is not viable, loosen the required context lines with `-C` (e.g. +`-C1`). Note: `--ignore-whitespace` only helps when the *only* difference in the +context is whitespace — it does not fix genuine line-offset mismatches. + Line ending issues: ```bash -git apply --ignore-space-change -v patch_file.patch +git apply --cached --ignore-space-change -v patch_file.patch ``` ## Git Apply vs Git Am @@ -58,4 +65,5 @@ git apply --ignore-space-change -v patch_file.patch - `git apply`: applies or stages changes without creating commits. - `git am`: applies patches with commit messages and author info preserved. -Use `git apply -v` for this workflow to keep commit creation explicit and controlled. +Use `git apply --cached -v` for this workflow to keep commit creation explicit and +controlled. From d7cd4795207667ff6072d093006fe42092d98fa6 Mon Sep 17 00:00:00 2001 From: nkoji21 <133028205+nkoji21@users.noreply.github.com> Date: Mon, 15 Jun 2026 14:27:21 +0900 Subject: [PATCH 5/5] =?UTF-8?q?docs(git-commit):=20patch=E7=94=9F=E6=88=90?= =?UTF-8?q?=E3=82=92git=20diff=20HEAD=E3=81=AB=E4=BF=AE=E6=AD=A3=E3=81=97b?= =?UTF-8?q?ody=E6=96=B9=E9=87=9D=E3=81=A8=E5=8F=82=E7=85=A7=E3=83=91?= =?UTF-8?q?=E3=82=B9=E3=82=92=E6=98=8E=E7=A2=BA=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit git diff(引数なし)はstaged hunkや新規ファイルを取りこぼすためgit diff HEADに統一。body方針を「Why/revertability説明は許容」と緩めGood例との矛盾を解消。git-commit-jaにreferencesの実パスを明示。 --- .agents/skills/git-commit-ja/SKILL.md | 5 +++-- .agents/skills/git-commit/SKILL.md | 13 +++++++++---- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/.agents/skills/git-commit-ja/SKILL.md b/.agents/skills/git-commit-ja/SKILL.md index 3cf4de6..4174fe0 100644 --- a/.agents/skills/git-commit-ja/SKILL.md +++ b/.agents/skills/git-commit-ja/SKILL.md @@ -6,8 +6,9 @@ allowed-tools: Bash, Skill --- Use `/git-commit` to perform the commit (granularity, revertability, `git apply` -staging, and `references/` all apply unchanged). It also forwards any `--path` / -`--push` arguments. +staging, and references all apply unchanged). It also forwards any `--path` / +`--push` arguments. The reference docs live under +`.agents/skills/git-commit/references/` (this skill has none of its own). ## Language override (this skill takes precedence) diff --git a/.agents/skills/git-commit/SKILL.md b/.agents/skills/git-commit/SKILL.md index db68183..526fc08 100644 --- a/.agents/skills/git-commit/SKILL.md +++ b/.agents/skills/git-commit/SKILL.md @@ -64,8 +64,9 @@ Never use interactive commands like `git add -p` or `git add --interactive` — Claude Code cannot handle them. Instead: ```bash -# 1. Generate patch for the target changes -git diff > patch.diff +# 1. Generate patch for the target changes (HEAD-relative so already-staged +# hunks and new files from a prior iteration are not lost) +git diff HEAD > patch.diff # 2. Verify before applying (no file changes on failure) git apply --cached --check patch.diff @@ -95,8 +96,9 @@ fix(git): remove deprecated option fix(git): remove deprecated option to prevent startup warning ``` -Body is optional. If you feel a body is necessary, the commit is likely too large — -consider splitting it. +Body is optional. Add one only to explain Why or revertability when the subject +alone is insufficient. If a body is needed just to enumerate *what* changed, the +commit is likely too large — consider splitting it. Do not add a `Co-Authored-By` or any agent-identifying footer. This skill is shared across Claude / Codex / Cursor, so hardcoding a single agent name would mislabel @@ -118,4 +120,7 @@ commit. Never push to `main`/`master` directly — create a feature branch first. +If `--path ` was also given, the push commands must run inside `` too — +`references/push.md` shows where to prepend `cd &&`. + Read `references/push.md` for the exact branch/upstream checks and push commands.