# Tidy First — AI Code Refactoring Skill for Agents

> Skill teaching AI agents Kent Beck's Tidy First methodology. Make small structural improvements before behavior changes to keep codebases clean and maintainable over time.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

Save as `~/.claude/skills/tidy-first/SKILL.md`:

```markdown
# Tidy First Skill

Before making behavioral changes, consider small structural tidyings.
Apply these patterns when code is messy enough to slow you down.
```

## What is Tidy First?

Tidy First is Kent Beck's methodology for software maintenance: make small structural improvements (tidyings) before changing behavior. Instead of big refactors, you make tiny, safe cleanups that make the next change easier. This skill teaches AI agents to apply Tidy First principles — recognizing when to tidy, which tidyings to apply, and how to keep them separate from behavior changes.

**Answer-Ready**: Tidy First is Kent Beck's code maintenance methodology. Small structural improvements before behavior changes. This skill teaches AI agents 15+ tidying patterns — guard clauses, extract helpers, normalize symmetries, dead code removal. Keeps codebases clean without risky refactors.

**Best for**: AI agents maintaining and evolving codebases. **Works with**: Claude Code, Cursor, any AI coding tool. **Setup time**: Under 1 minute.

## The 15 Tidyings

### 1. Guard Clauses

```python
# Before (nested)
def process(data):
    if data is not None:
        if data.is_valid():
            return transform(data)
    return None

# After (guarded)
def process(data):
    if data is None:
        return None
    if not data.is_valid():
        return None
    return transform(data)
```

### 2. Dead Code Removal

```python
# Remove code that is never called
# Remove commented-out code
# Remove unused imports
```

### 3. Normalize Symmetries

```python
# Before (inconsistent)
if user.is_admin:
    grant_access()
if not user.is_blocked:
    show_content()

# After (symmetric)
if user.is_admin:
    grant_access()
if user.is_active:
    show_content()
```

### 4. Extract Helper

```python
# Before
total = sum(item.price * item.quantity for item in cart if not item.is_deleted)

# After
def calculate_cart_total(cart):
    return sum(item.price * item.quantity for item in cart if not item.is_deleted)

total = calculate_cart_total(cart)
```

### 5. Inline Helper (Reverse of Extract)

When a helper is used only once and the name adds no clarity, inline it.

### 6. Reorder Statements

Move related code together. Group variable declarations near their usage.

### 7. Explicit Parameters

```python
# Before (implicit)
def send_email():
    to = config.admin_email  # Hidden dependency

# After (explicit)
def send_email(to: str):
    ...
```

### 8-15. More Tidyings

| # | Tidying | When |
|---|---------|------|
| 8 | Chunk statements | Group related lines with blank lines |
| 9 | Extract constants | Magic numbers → named constants |
| 10 | Rename variables | Unclear names → descriptive names |
| 11 | Remove duplication | Two identical blocks → one function |
| 12 | Simplify conditionals | Complex boolean → named function |
| 13 | Flatten nesting | Deep nesting → early returns |
| 14 | Split phase | One function doing two things → two functions |
| 15 | Introduce type | Raw dict/tuple → named class/dataclass |

## When to Tidy

```
Ask yourself:
1. Is the code I need to change messy enough to slow me down? → Tidy first
2. Is the tidying small (< 5 minutes)? → Do it now
3. Is the tidying large? → Separate PR, or skip for now
4. Am I unsure if the code is used? → Don't tidy, leave it
```

## Rules for AI Agents

1. **Tidy in separate commits** — Never mix structural and behavioral changes
2. **Small tidyings only** — Each tidying should be < 10 lines changed
3. **One tidying per commit** — Reviewable, revertable
4. **Tidy what you touch** — Only tidy code you are about to change
5. **Don't tidy speculatively** — No tidying "just in case"

## FAQ

**Q: How is this different from refactoring?**
A: Tidying is a subset of refactoring. Tidyings are small (minutes), safe, and done immediately before a behavior change. Refactoring can be large and risky.

**Q: Should AI always tidy first?**
A: No. Only tidy if the mess slows you down. If the code is clear enough, go straight to the behavior change.

**Q: Where does this come from?**
A: Kent Beck's book "Tidy First?" (2023). He is also the creator of TDD and extreme programming.

## Source & Thanks

> Based on Kent Beck's "Tidy First?" (2023).
>
> [tidyfirst.substack.com](https://tidyfirst.substack.com) — Kent Beck's newsletter

<!-- ZH -->

## 快速使用

保存为 `~/.claude/skills/tidy-first/SKILL.md`。

## 什么是 Tidy First？

Kent Beck 的代码维护方法论：行为变更前先做小的结构改进。

**一句话总结**：Kent Beck 代码维护方法论，行为变更前小结构改进，15 种 tidying 模式（guard clause/提取辅助/去死代码/重命名），AI Agent 代码维护必备。

## 15 种 Tidying

1. Guard Clauses — 早返回减少嵌套
2. 死代码删除
3. 对称性归一化
4. 提取辅助函数
5. 内联辅助函数
6. 重排语句
7. 显式参数
8-15. 分块/常量/重命名/去重/简化条件/扁平化/拆分阶段/引入类型

## 规则

- 结构和行为分开提交
- 每个 tidying < 10 行变更
- 只 tidy 即将修改的代码

## 来源与致谢

> Kent Beck "Tidy First?" (2023)

---
Source: https://tokrepo.com/en/workflows/905bfdbf-dbb4-45e5-b3e3-601ab52d9ef1
Author: Skill Factory