Chapter 17 · Best Practices and Team Norms

Chapter goals: Summarize the best practices for using Claude Code in production teams, establish team norms, and avoid common pitfalls.

17.1 The Golden Rules

Based on hundreds of real-world deployments, these are the non-negotiable principles:

Rule 1: CLAUDE.md Is Your First Investment

# Before doing anything else, create CLAUDE.md
# It is the highest-ROI file in your project

A good CLAUDE.md saves hours of repeated context-setting per session. See Chapter 3 for the template.

Rule 2: Test Before Trusting

Never let Claude Code modify production code without verification:

> Make the changes, then run all tests. If any fail, fix them before committing.

Always have pytest tests/ -x or equivalent in your CLAUDE.md as a hard constraint.

Rule 3: One Task Per Session

Don't dump ten requirements into one conversation:

# ❌ Bad
> Refactor the auth module, add dark mode, fix the login bug, and update docs

# ✅ Good
> Task 1: Refactor the auth module. Run tests after each change.
> [After completion]
> Task 2: Add dark mode support.

Each session has有限 context; splitting tasks avoids confusion and makes rollback easier.

Rule 4: Git Is Your Safety Net

Commit often. Every logical unit of work should be a commit:

> Commit this change with message "feat(auth): add OAuth2 support"

If something goes wrong, git reset --hard HEAD~1 is your undo button.

17.2 Common Pitfalls and Solutions

Pitfall 1: The Context Bloat

Symptom: Claude starts forgetting earlier decisions in long sessions. Solution: Use /compact proactively; externize state to PROGRESS.md; split into multiple sessions.

Pitfall 2: Silent Failures

Symptom: Claude says "done" but tests are failing. Solution: Always add "run tests and show me the results" as a硬 constraint; configure PostToolUse hooks to auto-run tests.

Pitfall 3: Permission Paralysis

Symptom: Every action requires confirmation, slowing工作 down. Solution: Pre-approve common commands in settings.json; use --allowedTools for one-off restrictive sessions.

Pitfall 4: Over-Reliance

Symptom: The team stops understanding the codebase because Claude does everything. Solution: Require code review for all AI-generated changes; use Maker-Checker patterns for critical modules.

17.3 Team Norms Template

Copy this into your team's CLAUDE.md:

## Team Conventions

### Code Quality
- All new code must pass `pnpm test` and `pnpm lint`
- Type annotations required for all public APIs
- Document complex logic with comments

### Git Workflow
- Conventional Commits: `feat(scope): description`
- Never force-push to main
- Create a branch for each feature

### Security
- Never commit API keys or secrets
- Use environment variables for all sensitive values
- Run `npm audit` before committing dependencies

### Review
- AI-generated code must be reviewed by a human before merge
- Flag any suspicious behavior to the team lead

17.4 When Not to Use Claude Code

Claude Code is powerful but not万能. Avoid it when:

• Time-critical hotfixes: the human can fix faster than the agent can plan;
• Completely unfamiliar domains: if no one on the team understands the code, the agent will too;
• One-off experiments: spending 30 minutes setting up the harness for a 5-minute task is反效率;
• High-security operations: things like database migrations in production should remain human-only.

Chapter Summary

• CLAUDE.md is the highest-ROI first step;
• Test before trusting; one task per session; commit often;
• Watch for context bloat, silent failures, permission paralysis, and over-reliance;
• Claude Code is not万能 — know when to use it and when to do it yourself.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is considered the highest-ROI first step when starting a new project with Claude Code?

2. What is the safest approach when Claude Code modifies production code?

3. Why is 'one task per session' recommended?

4. When should you NOT use Claude Code?

🛠️ Hands-on Practice

1. Write a CLAUDE.md for your team's project incorporating the norms from this chapter.
2. Deliberately make a wrong change via Claude Code; observe how the test hook catches it.
3. Run the same task in two sessions vs. one long session; compare token cost and output quality.

Congratulations! You have completed the Claude Code course. Continue to the next course or explore advanced topics.