Teaching Claude Code Your Standards

Ever had an AI refactor your entire file when you asked for a one-line fix? Or add comments to every function?

Claude Code's power comes from configuration. Without clear instructions, it's chaotic. With them, it becomes an extension of your development standards. This article shows how I've configured Claude Code to enforce immutability, follow TDD, automate workflows, and maintain consistency.

Note: AI tooling moves fast. This reflects my current workflow.

Know What You're Doing First

Critical: Don't blindly trust AI output. You must understand what the code does before shipping it.

Claude Code is a productivity multiplier, not a replacement for engineering judgment. It automates patterns you already know, enforces standards you've already defined, and catches mistakes you'd catch in review - but faster.

Before using these configs:

• Understand the fundamentals - Know why immutability matters, not just that it's a rule
• Review every change - Read diffs before committing. AI makes mistakes.
• Test everything - Run tests, check behavior. Don't assume it works.
• Own the output - You ship it, you're responsible. AI is a tool, not an excuse.

The configs below work because I know what good code looks like in my context. They encode decisions I've already made. If you copy them without understanding why, you'll ship bad code faster.

Use AI to accelerate what you already know how to do well.

The .claude/ Directory

Global config lives at ~/.claude/.

Structure:

~/.claude/
├── CLAUDE.md # Global instructions
├── docs/     # Conventions (git, typescript, testing, etc.)
├── skills/   # Custom slash commands
└── agents/   # Specialized workflows for specific tasks

Write Short, Prescriptive Docs

Forget lengthy style guides. Write terse, imperative docs. Examples:

Bad: "We generally prefer to avoid using any in TypeScript because it defeats the purpose of type safety."

Good: "No any - use unknown if needed"

Your docs become the AI's memory. Every session, it reads them.

Custom Skills = Workflow Automation

Skills are slash commands that trigger workflows. Mine:

• /ship - Stage all, commit, push
• /create-pr - Create PR with template
• /coverage - Check test coverage on unstaged changes
• /safe-repo - Scan for leaked secrets

Before: Manually running commands every deployment

# Manual commands
git add -A
git commit -m "fix: update validation logic"
git push
git status  # verify it worked

After: /ship - done

# Claude handles: status check, staging, commit with style-matched message, push, verification

Structure:

skills/ship/
└── skill.md

The markdown defines the workflow. AI executes it.

Enforce Immutability Through Instructions

I mandate immutability in code-principles.md:

## Immutability (mandatory)

- No array mutations: `push`, `pop`, `splice`, `shift`, `unshift`
- No object mutations: `obj.key=`, `delete obj.key`
- Use: spread `[...]`, `slice`, `map`, destructuring

The AI catches mutations I'd miss in review.

TDD By Default

My testing.md enforces test-first:

## Rules

- Prefer `vi.spyOn` over `vi.mock` for your own code
- Only use `vi.mock` for third-party libraries
- Test output must be pristine (zero warnings/errors)

Fewer mocks = more confidence.

Concision Is a Feature

My global instruction: "Extreme concision in all interactions and commits. Sacrifice grammar for brevity."

Results:

• Faster responses
• Less noise
• Commit messages match my style

What Changes

Immutability enforcement:

• AI catches mutations I'd miss in review
• Array mutation bugs get caught before commit
• Consistent patterns across codebase

Commit consistency:

• Commits follow conventional commit style
• Messages match my terse style
• PR descriptions follow template structure

Code review:

• Fewer style-related comments
• Less back-and-forth on conventions
• Reviews focus on logic, not formatting

Learnings

1. Invest in docs early - They compound. Every session benefits.
2. Skills > repetition - If you do it 3x, make it a skill.
3. Prescriptive > descriptive - "Do X" beats "we usually prefer X"
4. Test your instructions - AI follows literally. Ambiguity = inconsistency.
5. Version control your config - Treat .claude/ like code.

The Setup

# Global config
~/.claude/CLAUDE.md

# Project-specific overrides (optional)
.claude/PROJECT.md

AI reads both. Project overrides global.

My full config: github.com/helderberto/dotfiles

Result

Consistent code, faster reviews, fewer "why did you do that?" moments. The AI becomes an extension of your standards, not a wildcard.

Wrapping Up

AI without constraints is unpredictable. With clear docs, custom skills, and enforced standards, it becomes reliable.

Invest time upfront defining your standards. The AI will enforce them consistently across every session. No more hoping it does the right thing.

The config is the product. Treat it like code: version control it, test it, refactor it.

Teach once. Enforce forever.

Comments

[kxbnb]

I have about 15 skills in my .claude/ directory and the prescriptive > descriptive thing is real. "No any -- use unknown" works. "We generally prefer to avoid any" gets ignored half the time. I built a similar /ship skill that runs lint, tests, and conventional commit formatting in one shot and it compounds fast across a day with 20+ commits.

The thing I'd add is that versioning .claude/ config matters more than you'd expect across multiple repos. I've had skills that work perfectly in one project silently do the wrong thing in another because the conventions differ. Scoping per-project in .claude/CLAUDE.md vs global in ~/.claude/CLAUDE.md catches that early.

[Helder Burato Berto]

Thanks for sharing your learnings. Glad the article was helpful.

I agree that scoping some rules/skills per project make totally sense.