10.4 Team Standards & Conventions

Course: Claude Code - Power User Section: Customizing Claude Code Video Length: 2-5 minutes Presenter: Daniel Treasure

Opening Hook

Your team has rules. Write imperative commit messages. Use scope prefixes. One change per commit. One-liners should be short. These rules live in your head and your code reviews. Claude Code can enforce them before you review, if you give it the rules upfront.

Key Talking Points

1. Standardizing Claude's Behavior Across the Team

Define conventions in CLAUDE.md so they're discoverable and consistent
Use custom commands to automate enforcement (commit message formatter, style checker)
Set permissions and tools so Claude respects guardrails
Commit standards to git—new team members inherit them automatically What to say: "Standards without automation become complaints in pull request reviews. Automate them with Claude, and everyone codes the same way without being told." What to show on screen: CLAUDE.md with "Conventions" section. Show a commit message before and after automation.

2. Clear Commit Authorship

Use "Co-Authored-By" lines for paired work
Attribution fields in settings: attribution.commit and attribution.pr
Show who worked on the code: human + Claude
Build trust by being transparent about AI involvement What to say: "When Claude helps write code, the commits should say so. Not to blame Claude, but to document the process. 'Claude helped with X' is useful information for future maintainers." What to show on screen: Commit history showing Co-Authored-By. Compare with attribution.commit field in ~/.claude/settings.json or .claude/settings.json.

3. Commit Style Conventions

Imperative mood: "add feature" not "added feature" or "adds feature"
Scoped prefixes: feat(auth), fix(login), docs(readme), test(auth)
First line: 50 chars max, summarize the "what"
Body (optional): explain the "why" and "how", 72 chars per line
One logical change per commit What to say: "Good commit messages are gold. Future-you will thank you when you're debugging and need to understand 'why was this decision made?' Read the commit." What to show on screen: Before: messy commit history with unclear messages. After: clean history with clear scopes and imperatives. Git log showing readability.

4. Enforcing Standards with Custom Commands

Create /commit-template that guides Claude to follow conventions
Create /scope-checker that validates scope prefixes
Define these in .claude/skills/ so they're team-wide
Reference them in CLAUDE.md: "Use /commit to format commit messages" What to say: "Automation isn't about punishment. It's about making the right thing the easy thing. If your team's standard is 'imperative + scope', Claude should default to that." What to show on screen: Running /commit command and showing the output follows conventions. Show the skill definition that enforces the rules.

5. PR and Contribution Guidelines

PR title format: same as commit (scope-based)
PR body structure: what changed, why, testing done
Link to related issues
Mention breaking changes What to say: "PRs are conversations. Good structure makes them faster. Claude can help generate PR bodies that include everything reviewers need." What to show on screen: PR template in CLAUDE.md or .github/pull_request_template.md. Show Claude generating a PR description that follows the template.

Demo Plan

Open CLAUDE.md and show a "Conventions" section with commit rules
Show .claude/settings.json with attribution fields:
attribution.commit: "Co-Authored-By: Claude <claude@anthropic.com>"
attribution.pr: "Co-Authored-By: Claude <claude@anthropic.com>"
Create a custom skill for commit messages (from 10.3) that enforces:
Imperative mood
Scope prefix
50-char limit
Make a code change and run claude /commit to show enforced formatting
View the git log to show consistency
Generate a PR description using a skill that includes title, body, links

Code Examples & Commands

CLAUDE.md with conventions section:

## Conventions

### Commit Messages
- Use imperative mood: "add", "fix", "refactor" (not "added", "fixed", "refactoring")
- Scope prefix: feat(scope), fix(scope), docs(scope), test(scope)
- First line: max 50 characters
- Body: optional, explain "why" not "what"
- Example: `feat(auth): add JWT token refresh endpoint`

### PR Title Format
- Same scope prefix as commits: feat(scope): description
- Limit to 72 characters
- Link related issues: "Closes #123" or "Ref #456"

### One Change Per Commit
- Don't mix refactoring with feature development
- Don't mix unrelated bug fixes
- Each commit should be deployable on its own

### Code Attribution
- All commits include Co-Authored-By for AI-assisted work
- Format: `Co-Authored-By: Claude <claude@anthropic.com>`
- Generated automatically by `.claude/settings.json`

~/.claude/settings.json with attribution:

{
  "attribution": {
    "commit": "Co-Authored-By: Claude <claude@anthropic.com>",
    "pr": "Co-Authored-By: Claude <claude@anthropic.com>"
  }
}

.claude/settings.json (project-level) with team standards:

{
  "attribution": {
    "commit": "Co-Authored-By: Claude <claude@anthropic.com>",
    "pr": "Co-Authored-By: Claude <claude@anthropic.com>"
  },
  "outputStyle": "concise",
  "model": "claude-opus-4-6"
}

Custom skill: commit-formatter

---
name: commit
description: "Generate a properly formatted commit message following team conventions"
argument-hint: "(optional) override scope (default: auto-detect from files)"
user-invocable: true
allowed-tools: ["bash", "read"]
model: "claude-opus-4-6"
---

# Commit Message Formatter

Follow these exact conventions:
1. Type(scope): description
2. Types: feat, fix, docs, style, refactor, perf, test, chore
3. Scope: auto-detect from changed files, or use $ARGUMENTS
4. Description: imperative mood ("add" not "added"), max 50 chars
5. Body: optional, explain "why", max 72 chars per line
6. Include Co-Authored-By footer

Steps:
1. Read staged changes: !`git diff --cached --name-only`
2. Determine type (feat vs fix vs chore)
3. Detect scope from filenames
4. Write message in format: type(scope): imperative-description

Example outputs:
- feat(auth): add password reset endpoint
- fix(login): resolve race condition in session validation
- docs(readme): update installation instructions
- refactor(api): simplify error handling middleware

Output ONLY the commit message, ready to use.

Custom skill: pr-description

---
name: pr
description: "Generate a PR description with title, body, and checklist"
argument-hint: "(optional) override title"
user-invocable: true
allowed-tools: ["bash", "read"]
model: "claude-opus-4-6"
---

# PR Description Generator

Generate a complete PR description following team conventions.

Get the branch diff: !`git diff main...$(git rev-parse --abbrev-ref HEAD) --stat`

Format:
## Title
[type(scope): description] - max 72 chars, imperative mood

## What Changed
Bullet list of changes

## Why
Explain motivation and context

## Testing Done
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Related Issues
Closes #[issue] or Ref #[issue]

## Breaking Changes
None / List any breaking changes

Viewing git log with scoped commits:

# Show commits with nice formatting
git log --oneline --decorate

# Example output:
# a1b2c3d (HEAD -> main) feat(auth): add OAuth2 integration
# d4e5f6g fix(login): resolve password validation bug
# h8i9j0k docs(readme): update API documentation

Gotchas & Tips

Gotcha: Commit style conventions are habits. New team members won't follow them without automation. Use custom commands to make the right thing the easy thing.

Tip: Attribution shows transparency. When reviewers see "Co-Authored-By: Claude", they know AI assisted, which is valuable context.

Tip: Don't over-engineer scopes. If you have 20 scopes, simplify. Common ones: auth, api, ui, db, docs, test, chore.

Gotcha: If CLAUDE.md says one thing and your custom command does another, team members will be confused. Keep them in sync.

Tip: Document the "why" in commit bodies, not just the "what". "Optimize loop to O(n) instead of O(n²)" is better than "change loop".

Lead-out

Standards keep your team aligned. Next, we'll add permission profiles—a way to define exactly what Claude can and cannot do in different contexts. A code reviewer sees different capabilities than a bot running in CI.

Reference URLs

Conventional Commits specification (conventionalcommits.org)
Git commit message best practices
.github/pull_request_template.md documentation
Attribution in Claude Code settings

Prep Reading

Review your team's last 20 commits. Are they consistent?
What standards do you wish Claude would follow automatically?
What's the cost of enforcing these manually in reviews?

Notes for Daniel: Standards are about team health, not perfection. Show how automation removes friction from code review. The demo should feel liberating—"we don't argue about this anymore, Claude just does it"—not restrictive. Emphasize that standards evolve; CLAUDE.md and custom commands are living documents.

Quick Reference