Skip to content

Samsen Internal Framework

This is Samsen's internal framework content for Claude Code & Agentic Coding. It is read-only reference material.

Claude Code — Git Workflow

The Principle

Claude Code should follow the same git workflow as any other contributor. Feature branches, meaningful commits, pull requests, review. The fact that an AI made the changes doesn't change the process.

Branch Strategy

Always Branch

Never let Claude Code work directly on main or production branches. Always create a feature branch:

  • feature/add-card-component
  • fix/button-hover-state
  • update/token-spacing-scale

Claude Code can create branches, switch branches, and manage commits. Use descriptive branch names that make the PR self-explanatory.

Branch Naming Convention

A consistent convention helps both humans and CI:

feature/  — New components, features, pages
fix/      — Bug fixes
update/   — Modifications to existing code
refactor/ — Structural changes without behavior change
docs/     — Documentation updates
chore/    — Build, config, dependency updates

Commit Patterns

Meaningful Commit Messages

Claude Code can be prompted to write good commit messages:

"Commit this change with a descriptive message explaining what was added and why."

Good AI commits look like:

feat: add Card component with compact and default variants

- Uses design system tokens for spacing and typography
- Responsive: stacks vertically on mobile
- Includes hover elevation effect using --elevation-card-hover

Not:

update files

Atomic Commits

Encourage Claude Code to commit logical units of work:

  1. Commit the component file
  2. Commit the styles
  3. Commit the tests
  4. Commit the documentation update

This makes review easier and allows cherry-picking if needed.

Pull Request Workflow

Creating PRs

Claude Code can create pull requests via the GitHub CLI or API. A good PR includes:

  • Title — Clear, concise description of the change
  • Description — What changed, why, and any decisions made
  • Screenshots — If visual, include before/after
  • Testing notes — How to verify the change works

Reviewing AI-Generated PRs

Designers reviewing AI-generated PRs should focus on:

  1. Visual output — Does it look correct in the browser/Storybook?
  2. Behavior — Do interactions work as expected?
  3. Token usage — Does the diff show design system tokens (not hardcoded values)?
  4. CI status — Do all checks pass?

You don't need to understand every line of code. The combination of visual review + CI checks provides sufficient confidence for UI components.

When to Request Changes

Request changes when:

  • Visual output doesn't match the design intent
  • Hardcoded values appear where tokens should be
  • A new dependency was added unnecessarily
  • Tests are missing or insufficient
  • The change affects files it shouldn't

Working with Multiple Contributors

When both humans and AI contribute to the same codebase:

Avoid Conflicts

  • AI works on feature branches, never on files being actively edited by humans
  • Communicate which components/files are "in progress" to avoid overlap
  • Pull latest from main before starting AI work

Code Style Consistency

  • Run linting after every AI change (Claude Code can do this automatically)
  • Use Prettier or equivalent for consistent formatting
  • AI-generated code should be indistinguishable from human-written code in style

Attribution

Commits from Claude Code are authored by the human who prompted the work. The human is responsible for the output, just as they would be responsible for code written by a contractor or junior developer.

Common Git Operations with Claude Code

# Ask Claude Code to:
"Create a new branch called feature/notification-banner"
"Stage and commit the changes with the message: feat: add notification banner"
"Push this branch and create a PR targeting main"
"Pull the latest from main and rebase our branch"
"Show me the diff of what we've changed"
"Undo the last commit but keep the changes"

Claude Code handles git operations natively. You describe what you want in plain language.

Safety Practices

  • Never force push to shared branches
  • Never rewrite history on branches others are working on
  • Always pull before pushing to avoid conflicts
  • Review the diff before approving any PR, especially for large changes
  • Use draft PRs for work in progress that's not ready for review