나의 Claude Code 모범 사례

Claude Code를 사용한 AI 프로그래밍을 지속적으로 수행하면서, 효율적인 개발 워크플로를 정리했습니다. 이 Claude Code 모범 사례는 세션 관리, 플래닝 모드, 버전 관리, 품질 보증, 코드 리뷰 등 핵심 프로세스를 다루고 있습니다.

Claude Code 핵심 사용 기법

하나의 세션에서 하나의 태스크를 완료하고, 각 태스크 완료 후 /clear로 컨텍스트 압축을 방지합니다.
단일 파일의 간단한 수정 외에는 모두 plan 모드를 사용합니다. 더 복잡한 경우에는 spec 기반 접근법을 사용합니다.
think, think hard, ultrathink을 사용하여 Claude가 복잡한 문제를 더 깊이 생각하게 합니다.
변경할 때마다 Git으로 관리하고, 각 태스크별로 브랜치를 생성하여 완료 후 병합합니다.
Claude Code Hooks와 pre-commit 등의 도구 체인으로 코드 품질을 보장하며, Claude에게 포맷 검사 등을 맡기지 않습니다.
몇 차례 대화로 문제가 해결되지 않으면 새로운 세션을 열어 다시 처리합니다.
태스크에 큰 문제가 발생하면 git checkout .으로 마지막 커밋 상태로 돌아가서 다시 시작합니다.
worktree를 사용하여 여러 태스크를 동시에 처리하고 Claude Code에 병합을 맡깁니다. 다만 더 흔한 경우는 여러 창을 열어 여러 프로젝트를 병렬로 처리하는 것입니다(예: 같은 기능의 프론트엔드와 백엔드).
Claude Code는 프로그래밍뿐만 아니라 정보 정리와 수집에도 활용할 수 있습니다.
claude --dangerously-skip-permissions로 전체 권한을 부여합니다. 아직까지 문제를 겪은 적은 없습니다.
각 태스크 완료 후 새 창을 열어 코드 리뷰용 Subagent로 코드 리뷰를 수행합니다.

Claude Code 슬래시 명령어 완전 가이드

Claude Code의 슬래시 명령어는 프로그래밍 효율을 높이기 위한 핵심 도구입니다. 여기서는 Claude Code에서 가장 자주 사용되는 슬래시 명령어와 그 사용법을 소개합니다.

`/init`

CLAUDE.md 파일을 초기화하여 프로젝트의 배경, 요구사항, 제약 조건 등을 기록합니다.
저는 프로젝트가 어느 정도 진행된 후에 이 명령어를 사용합니다.

`/memory`

개인 또는 프로젝트의 범용 메모리를 조회하고 관리합니다. 즉, CLAUDE.md 파일의 내용을 관리합니다.
터미널에서 #으로 시작하여 빠르게 호출할 수 있습니다.
개발 과정에서 범용적인 제약으로 사용할 수 있다고 판단되는 내용이 있으면 바로 추가합니다. 변경 후 Claude에게 추가하라고 하면 됩니다.

`/add-dir`

지정한 디렉토리의 모든 파일을 Claude의 컨텍스트에 추가하여 다중 프로젝트 연동을 실현합니다.
개인적으로는 터미널에서 경로를 복사하여 Claude에게 보여주는 방식을 선호합니다. 이 명령어는 잘 사용하지 않습니다. 이렇게 하면 강제로 확인하게 할 수 있기 때문입니다.
다중 프로젝트 연동이 잦은 경우 CLAUDE.md에 경로를 직접 기록해 두면, /clear 후에도 기억이 유지됩니다.

`/clear`

현재 세션의 컨텍스트를 초기화하고 새로운 태스크를 시작합니다.
태스크를 완료할 때마다 이 명령어를 사용하여 컨텍스트가 너무 커져서 자동 압축되는 것을 방지합니다.
정보 손실을 걱정할 필요가 없습니다. 중요한 정보는 CLAUDE.md에 기록해야 합니다. 하나의 세션은 하나의 태스크를 위한 것입니다.

`/compact`

현재 세션의 컨텍스트를 압축하고, 요점을 유지하면서 현재 태스크를 계속합니다.
기본적으로 직접 사용하지 않습니다. 압축하면 세부 정보가 손실되어 후속 응답 품질에 영향을 미치기 때문입니다.
태스크가 너무 크다면 컨텍스트를 압축하는 것이 아니라 태스크를 분할해야 합니다.

`/mcp`

MCP를 제어하고 관리합니다.
가장 많이 사용하는 MCP는 Context7과 chrome-devtools-mcp입니다.

`/agent`

Subagent의 사용을 조회하고 관리합니다.
GitHub의 Agent 리포지토리에서 정의된 Agent를 사용할 수 있습니다.
가장 많이 사용하는 SubAgent는 /code-review-ai:ai-review이며, 주로 코드 리뷰에 사용합니다.

`/hooks`

Claude Code Hooks를 조회하고 관리합니다.

예를 들어, 코드 완료 후 자동으로 포맷을 실행하는 설정입니다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$CLAUDE_PROJECT_DIR\" && make format",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

예를 들어, 메시지 완료 후의 시스템 알림 설정입니다.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title '🚀 통지' -subtitle '需要你的指令' -message 'Claude 正等待下一步操作' -sound 'Pop' -execute '/usr/local/bin/code /Users/wyx/code'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title '✅ 통지' -subtitle '任务已完成' -message '当前任务已完成' -sound 'Pop' -execute '/usr/local/bin/code /Users/wyx/code'"
          }
        ]
      }
    ]
  }
}

`/tasks`

백그라운드 태스크를 조회하고 관리합니다. !로 빠르게 트리거할 수 있습니다.
수동으로 사용하는 경우는 거의 없습니다. 새 창을 열어 실행 상황을 확인하고 오류를 수동으로 복사하는 것을 선호합니다.

`/export`

현재 세션의 내용을 내보냅니다.
다른 AI 도구로 내용을 분석해야 할 때 사용합니다. 내보내서 다른 AI 도구에 붙여넣을 수 있습니다.

커스텀 명령어 공유

Claude Code는 커스텀 명령어를 지원합니다. md 파일을 작성하여 ~/.claude/commands/ 디렉토리에 배치하면 됩니다.

`/commit`

# Commit Message 생성 규범

你是一位资深的软件工程师和代码审查专家，专注于生成高质量、符合 Git Conventional Commits 规范的提交信息，并且执行git add和git commit命令，不执行git push操作。

## 核心任务

根据用户提供的代码变更（diff）或暂存区内容，执行以下分析并生成提交信息：

1. **原子性分析 (Atomic Check)**:
    * 首先分析代码变更是否过于复杂或包含多个不相关的改动。
    * 如果包含多个逻辑独立的改动（例如同时修改了 UI 和后端 API，且两者无直接依赖），**请优先建议用户拆分提交**，并给出拆分建议。
    * 如果改动是原子的（Atomic），则继续生成提交信息。

2. **生成提交信息 (Commit Generation)**:
    * 严格遵循 **Conventional Commits** 格式。
    * **语言要求**: 提交信息的标题（Subject）和正文（Body）必须使用**中文**。
    * **最后说明**：这个commit是谁提交的，例如"由Claude AI助手生成"。

    * **格式结构**:

        ```text
        <emoji> <type>(<scope>): <subject>

        <body>
        ```

## 详细规则

### 1. Header 格式

* **Emoji**: 根据改动类型选择最准确的表情符号（见下表）。
* **Type**: 使用标准的英文类型（如 `feat`, `fix`），保持工具兼容性。
* **Scope** (可选): 用英文括号包裹，简短说明改动影响的模块或文件名。
* **Subject**: 简练的**中文**描述，不超过 50 个字符，不要以句号结尾。

### 2. Body 内容 (至关重要)

正文部分必须清晰分段，包含以下两部分：
* **What (做了什么)**: 使用无序列表 (`- `) 详细列出具体的代码改动点。
* **Why (为什么做)**: 解释改动的动机、解决的问题或带来的优化。

### 3. 类型映射表 (Type/Emoji Mapping)

| Type | Emoji | 含义 | 适用场景 |
|:---|:---|:---|:---|
| **feat** | ✨ | 新功能 | 引入新特性或功能 |
| **fix** | 🐛 | 修复 Bug | 修复生产环境或开发中的错误 |
| **docs** | 📝 | 文档 | 仅修改文档 (README, API doc) |
| **style** | 💄 | 格式/样式 | 代码格式化、UI 微调 (不影响逻辑) |
| **refactor** | ♻️ | 重构 | 代码结构调整，既不修 Bug 也不加功能 |
| **perf** | ⚡️ | 性能 | 提升性能的改动 |
| **test** | ✅ | 测试 | 增加或修改测试代码 |
| **build** | 📦 | 构建 | 构建系统或外部依赖变动 |
| **ci** | 👷 | CI/CD | CI 配置文件或脚本变动 |
| **chore** | 🔧 | 杂项 | 其他琐碎改动 |

## 输出示例

**输入**: 用户修改了登录逻辑，增加了验证码校验，并修复了一个空指针报错。

**输出**:

✨ feat(auth): 增加登录时的验证码校验机制

- 在 `LoginController` 中集成验证码服务
- 更新前端登录表单，增加验证码输入框
- 🐛 fix: 修复 `UserParams` 解析时的空指针异常

**原因 (Why):**
为了防止暴力破解攻击，提高账户安全性，因此引入强制验证码流程。同时顺带修复了测试中发现的潜在崩溃问题。

---

**注意**:
*   你可以执行提交commit的命令，但是最终的git push操作由用户执行，因为最终的提交信息需要用户确认。
*   最终输出只需包含建议的 Commit Message 内容，不需要额外的寒暄。

***

마치며

현재 이 Claude Code 모범 사례는 주로 백엔드 개발 경험에 기반하고 있습니다. 프론트엔드 부분의 최적화 전략은 아직 탐색 중입니다.

AI 보조 프로그래밍에서의 코드 품질 보장에 대해 더 자세히 알고 싶으시다면, "AI 프로그래밍 품질 관리: 코드 품질을 보장하는 5가지 방어선"을 참고해 주세요. Claude Code 프로그래밍에서의 5계층 품질 방어 체계에 대해 자세히 설명하고 있습니다.

이 Claude Code 기법과 사례는 끊임없이 발전하고 있으며, 이 글도 지속적으로 업데이트할 예정입니다.

"Claude 시스템 아키텍처 완전 해설" -- Claude Code 뒤에 있는 MCP, Skills, Subagents, Hooks 등의 컴포넌트를 깊이 이해하기
"Claude Skills란 무엇인가" -- Skills의 핵심 원리와 활용 시나리오
"Claude Subagent 완전 가이드" -- Subagent의 사용법과 커스터마이징 마스터하기
"Eclipse에서 Zed로: 한 개발자의 에디터 진화사" -- 나의 개발 도구 변천사