github

github

Flow

For implementation work other than patch bug fixes, proceed in this order.

1. Create an Issue.
2. Create a dedicated branch that includes the Issue number.
3. Implement.
4. Create a PR.
5. Check ahead / behind and whether it can be merged.
6. Merge with a merge commit.

Treat work where the judgment is unclear as the normal flow, not as a patch bug fix. Do not proceed with implementation that is subject to the normal flow without an Issue, without a dedicated branch, or without a PR. Do not start on the default branch.

For changes that span companies, teams, or areas of responsibility, clearly state the impact scope, verification details, and remaining risks in the Issue and PR.

Cases where the flow can be omitted

It can be omitted as a patch bug fix only when all of the following are satisfied.

• It is a minimal diff that fixes a clear defect in existing behavior.
• It does not include specification additions, design changes, data model changes, API contract changes, dependency changes, or changes to permissions, billing, or authentication.
• The change scope is local and does not affect other teams' work or repositories scheduled for integration.
• The value of fixing it immediately is clearly higher than the value of turning it into an Issue and building consensus.
• The user has explicitly requested patch handling, or equivalent Issue or PR context already exists.

Before starting

git status --short --branch
git fetch --prune

• Check the status of the default branch, current branch, and remote-tracking branch.
• If there are uncommitted changes, check their contents and ownership. Do not stage, commit, or modify changes unrelated to the current work.
• If the current branch is not the default branch, confirm whether it is for the current work.
• If tools or permissions necessary for Issue or PR operations, such as gh, are missing, report the shortage and confirm whether it is acceptable to proceed with only the local implementation first.

Issue

• First check whether an existing Issue exists. If not, create one before implementation.
• Write the purpose, background, acceptance criteria, impact scope, and verification policy.
• Write acceptance criteria as a task list (- [ ]) so that progress can be tracked.
• If it affects multiple companies or multiple areas, write the responsibility boundaries and review perspectives.
• Split into a granularity where the implementation unit is not too large.
• Do not start a large change while the Issue remains ambiguous.

Branch

• Create a dedicated branch that includes the Issue number.
• The name is <type>/<issue-number>-<short-kebab-summary>。
• type is one of feat, fix, refactor, docs, test, chore, ci, build.
• Before creating it, confirm that the base branch is up to date.
• Do not mix implementations for multiple Issues into one branch.
• Do not switch branches without the user's confirmation.

Implementation

• Implement in the smallest logical units in accordance with the Issue's acceptance criteria.
• If the scope expands, update the Issue and PR descriptions. Split into separate Issues if necessary.
• Perform tests, lint, type checks, E2E, and documentation updates according to the changes.
• Do not combine huge diffs that are hard to review into a single PR without reason.

Commit message

type: 説明 format. Use short Japanese sentences. In a monorepo, use type(scope): 説明 , and do not use parenthetical notation in order to keep the description short.

type is one of the following.

• feat new feature / fix bug fix / perf performance improvement / refactor improvement without functional change
• docs documentation / style style fix / test test / chore other
• ci CI/CD configuration / build build configuration / merge PR merge (for merge commits only)

How to decide the scope.

• Use the name of the top-level directory that had file changes (the directory name directly under the repository root).
• In a monorepo such as Turborepo, if you change something under apps/ or packages/, use the package name or app name under it (the leaf name). For apps/dashboard use dashboard, for packages/log use log.
• For changes that affect the entire repository, use repo.
• Write hidden directories including the leading dot. Use .agents, not agents.
• Do not express hierarchy with slashes.
• Do not use monorepo parent directories themselves, such as apps or packages, as the scope.
• Do not use abstract generic terms with no substance, such as workspace or design, or folder names that do not exist.

NG: feat(workspace): / feat(design): / feat(agents): / feat(apps): / feat(apps/dashboard): / feat(packages/log):
OK: feat(repo): / feat(.agents): / feat(.claude): / feat(dashboard): / feat(log):

How to write the description.

• End with an action. Such as do ~, add ~, fix ~, delete ~, implement ~.
• Do not end with a noun that does not involve an action.feat(api): ユーザー認証 instead of feat(api): ユーザー認証を追加。
• Do not include emoji.
• Split commits by logical scope (package, feature). Do not mix unrelated changes into a single commit.

Executing commits

• per file git diff and check the author of each change.
• git add . と git add -A Do not use
• Do not overwrite the committer. Always use the user's git config.
• Co-Authored-By Do not include

Only when all changes are by the agent and there are no lines edited by the user,--author explicitly indicate your own agent type with

git commit --author="Claude <noreply@anthropic.com>" -m "<message>"
git commit --author="Codex <noreply@openai.com>" -m "<message>"
git commit --author="Cursor Agent <cursoragent@cursor.com>" -m "<message>"

Use the line that matches the agent type that is actually running. Do not reuse examples from other agents. If there is even a partial change by the user, use the normal git commit .

• In an environment where the commit-msg hook automatically adds an unapproved Co-authored-by: , deal with it by installing a hook that removes it.git commit --no-verify Do not bypass the hook with
• If a force push is required for history modification, temporarily enable the guard's permission, push, and restore it after the work is done.

Git operation safety check

Before any Git operation (commit, push, branch creation, merge, rebase), run git fetch --prune . Then confirm the following.

• Whether the current branch has not already been merged into the default branch. If it has, warn and suggest switching branches.
• Whether the remote-tracking branch still exists. If it has been deleted, warn.
• Whether the local branch is behind the remote. If it is behind, suggest git pull --rebase .
• Whether it has diverged from the remote. If it has diverged, warn and suggest either rebase or merge.

Do not run git pull や git rebase without the user's approval. Do not delete a local branch without confirmation.

PR

gh pr create --body "<本文>"
gh pr create --body-file <file>

• Always specify the body explicitly.--fill Do not use Co-Authored-By .
• In the body, write the overview, changes, verification results, scope of impact, points you want reviewed, and remaining risks.
• Reference the target Issue in natural language. Write #<issue-number> in the background or overview of the body.
• Only when auto-close is needed, use an English keyword (such asCloses #N ) or link the Issue via GitHub's Development. Japanese synonymous expressions ("#N o kurōzu suru") will not trigger auto-close.
• Before creating it, push the local branch to upstream.
• Create it early as a Draft, and after implementation is complete, switch it to Ready for review.
• Do not merge while bypassing review, CI, or necessary verification.

Pre-merge checks

git fetch --prune
git status --short --branch

• The local branch must not be ahead / behind / diverged relative to upstream.
• The PR branch must not be behind the base branch.
• The PR must be mergeable, with no conflicts, and required CI, reviews, and checks must pass.

Remediation.

• If ahead, push and recheck.
• If behind or diverged, report to the user, confirm the rebase / merge / pull policy, and then synchronize.
• If the PR branch is behind the base branch, incorporate the base branch and rerun verification.
• Do not merge if there are conflicts, failed CI, unresolved reviews, or unconfirmed ahead / behind status.

Merge

Immediately beforehand, check git fetch --prune and ahead / behind once more.

gh pr merge <番号> --merge --subject "merge(scope): 説明" --body ""

• The merge method is merge commit. Do not use squash merge or squash commit. The only exception is when the user explicitly instructs it.
• Specify the subject and an empty body. Do not use the default merge commit message (Merge pull request #N from ...).
• Do not include PR numbers or Issue numbers (#N) in either the subject or the body.
• Since the merge prefix makes it explicit that this is a merge, do not write "merge" in the description.merge(api): foo をマージ instead of merge(api): foo を追加。

After merge

• Check the status of the target Issue. If auto-close was configured, confirm that it was closed. If it was not configured, close it manually with gh issue close <番号> .
• Delete the working branch only after confirming the remote state and the user's intent.
• If merge, review, or verification is on hold, or if the resolution is pending, do not close the Issue; leave the status and resumption conditions in a comment as pending review. This is to prevent duplicate filings.
• Do not file duplicate Issues for the same unresolved occurrence.
• If multiple Issues have been filed and closed for the same occurrence, treat the oldest Issue as the parent (source of truth), add a sub-issue relationship, close the later ones as duplicates, and comment the changes on each Issue.