yueqian-ai
1274 lines
52 KiB
HTML
1274 lines
52 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>Claude Code 工程师使用指南 v2.1</title>
|
||
<style>
|
||
:root {
|
||
--color-primary: #1677FF;
|
||
--color-primary-hover: #4096FF;
|
||
--color-primary-active: #0958D9;
|
||
--color-primary-bg: #E6F4FF;
|
||
--color-success: #52C41A;
|
||
--color-success-bg: #F6FFED;
|
||
--color-success-border: #B7EB8F;
|
||
--color-warning: #FAAD14;
|
||
--color-warning-bg: #FFFBE6;
|
||
--color-warning-border: #FFE58F;
|
||
--color-error: #FF4D4F;
|
||
--color-error-bg: #FFF2F0;
|
||
--color-error-border: #FFCCC7;
|
||
--color-info: #1677FF;
|
||
|
||
--bg: #F5F5F5;
|
||
--bg-container: #FFFFFF;
|
||
--bg-elevated: #FAFAFA;
|
||
--border: #D9D9D9;
|
||
--border-light: #F0F0F0;
|
||
--text-primary: #141414;
|
||
--text-secondary: #595959;
|
||
--text-tertiary: #8C8C8C;
|
||
|
||
--radius-sm: 6px;
|
||
--radius-md: 8px;
|
||
--radius-lg: 12px;
|
||
|
||
--shadow-sm: 0 1px 2px rgba(0,0,0,0.03), 0 1px 6px -1px rgba(0,0,0,0.02);
|
||
--shadow-md: 0 2px 4px rgba(0,0,0,0.04), 0 4px 12px -2px rgba(0,0,0,0.04);
|
||
--shadow-lg: 0 4px 8px rgba(0,0,0,0.06), 0 8px 24px -4px rgba(0,0,0,0.08);
|
||
|
||
--sidebar-w: 260px;
|
||
--header-h: 64px;
|
||
}
|
||
|
||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||
|
||
body {
|
||
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
|
||
'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei',
|
||
'Helvetica Neue', Helvetica, Arial, sans-serif;
|
||
background: var(--bg);
|
||
color: var(--text-primary);
|
||
line-height: 1.57;
|
||
font-size: 14px;
|
||
}
|
||
|
||
::-webkit-scrollbar { width: 6px; height: 6px; }
|
||
::-webkit-scrollbar-track { background: transparent; }
|
||
::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
|
||
::-webkit-scrollbar-thumb:hover { background: var(--text-tertiary); }
|
||
|
||
.header {
|
||
position: fixed;
|
||
top: 0; left: 0; right: 0;
|
||
height: var(--header-h);
|
||
background: rgba(255,255,255,0.85);
|
||
backdrop-filter: blur(12px);
|
||
border-bottom: 1px solid var(--border-light);
|
||
display: flex;
|
||
align-items: center;
|
||
padding: 0 2rem;
|
||
z-index: 100;
|
||
}
|
||
.header h1 {
|
||
font-size: 18px;
|
||
font-weight: 700;
|
||
background: linear-gradient(135deg, var(--color-primary), #722ED1);
|
||
-webkit-background-clip: text;
|
||
-webkit-text-fill-color: transparent;
|
||
background-clip: text;
|
||
}
|
||
.header .version {
|
||
margin-left: auto;
|
||
font-size: 12px;
|
||
color: var(--text-tertiary);
|
||
font-family: 'SF Mono', Monaco, monospace;
|
||
}
|
||
|
||
.sidebar {
|
||
position: fixed;
|
||
top: var(--header-h); left: 0; bottom: 0;
|
||
width: var(--sidebar-w);
|
||
background: var(--bg-container);
|
||
border-right: 1px solid var(--border);
|
||
overflow-y: auto;
|
||
padding: 1.25rem 0;
|
||
z-index: 90;
|
||
}
|
||
.sidebar .toc-label {
|
||
font-size: 12px;
|
||
text-transform: uppercase;
|
||
letter-spacing: 0.1em;
|
||
color: var(--text-tertiary);
|
||
padding: 0 1.25rem;
|
||
margin-bottom: 0.75rem;
|
||
}
|
||
.sidebar nav ol { list-style: none; padding: 0; counter-reset: toc; }
|
||
.sidebar nav li { counter-increment: toc; padding: 0; }
|
||
.sidebar nav a {
|
||
display: block;
|
||
padding: 0.5rem 1.25rem;
|
||
color: var(--text-secondary);
|
||
text-decoration: none;
|
||
font-size: 13px;
|
||
line-height: 1.4;
|
||
border-left: 2px solid transparent;
|
||
transition: all 0.15s;
|
||
}
|
||
.sidebar nav a::before {
|
||
content: counter(toc) ". ";
|
||
color: var(--color-primary);
|
||
font-weight: 600;
|
||
font-size: 12px;
|
||
margin-right: 0.4rem;
|
||
}
|
||
.sidebar nav a:hover {
|
||
color: var(--color-primary);
|
||
background: var(--color-primary-bg);
|
||
}
|
||
.sidebar nav a.active {
|
||
color: var(--color-primary);
|
||
border-left-color: var(--color-primary);
|
||
background: var(--color-primary-bg);
|
||
font-weight: 600;
|
||
}
|
||
|
||
.main {
|
||
margin-left: var(--sidebar-w);
|
||
margin-top: var(--header-h);
|
||
padding: 32px 40px 64px;
|
||
min-height: calc(100vh - var(--header-h));
|
||
max-width: 1200px;
|
||
}
|
||
|
||
section {
|
||
margin: 48px 0;
|
||
scroll-margin-top: calc(var(--header-h) + 1rem);
|
||
}
|
||
section h2 {
|
||
font-size: 24px;
|
||
line-height: 32px;
|
||
padding-bottom: 8px;
|
||
border-bottom: 1px solid var(--border);
|
||
margin-bottom: 20px;
|
||
color: var(--color-primary);
|
||
}
|
||
section h3 {
|
||
font-size: 20px;
|
||
line-height: 28px;
|
||
margin: 24px 0 12px;
|
||
color: #722ED1;
|
||
}
|
||
section h4 {
|
||
font-size: 16px;
|
||
line-height: 24px;
|
||
margin: 16px 0 8px;
|
||
color: var(--color-success);
|
||
}
|
||
|
||
.table-wrap { overflow-x: auto; margin: 20px 0; }
|
||
table {
|
||
width: 100%;
|
||
border-collapse: collapse;
|
||
font-size: 14px;
|
||
}
|
||
th, td {
|
||
padding: 10px 14px;
|
||
border: 1px solid var(--border);
|
||
text-align: left;
|
||
vertical-align: top;
|
||
}
|
||
th {
|
||
background: var(--bg-elevated);
|
||
font-weight: 600;
|
||
position: sticky;
|
||
top: 0;
|
||
}
|
||
td { background: var(--bg-container); }
|
||
tbody tr:hover td { background: var(--color-primary-bg); }
|
||
|
||
code {
|
||
background: var(--bg-elevated);
|
||
padding: 2px 8px;
|
||
border-radius: 4px;
|
||
font-family: 'SF Mono', 'Menlo', 'Courier New', monospace;
|
||
font-size: 13px;
|
||
color: var(--color-primary);
|
||
}
|
||
pre {
|
||
background: var(--bg-elevated);
|
||
border: 1px solid var(--border);
|
||
border-radius: var(--radius-md);
|
||
padding: 16px;
|
||
overflow-x: auto;
|
||
margin: 16px 0;
|
||
}
|
||
pre code {
|
||
background: none;
|
||
padding: 0;
|
||
color: var(--text-primary);
|
||
font-size: 13px;
|
||
line-height: 1.7;
|
||
}
|
||
|
||
.card-grid {
|
||
display: grid;
|
||
grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
|
||
gap: 16px;
|
||
margin: 20px 0;
|
||
}
|
||
.card {
|
||
background: var(--bg-container);
|
||
border: 1px solid var(--border);
|
||
border-radius: var(--radius-md);
|
||
padding: 24px;
|
||
transition: all 0.2s ease;
|
||
}
|
||
.card:hover {
|
||
border-color: var(--color-primary);
|
||
box-shadow: var(--shadow-md);
|
||
}
|
||
.card h4 { margin: 0 0 8px; color: var(--text-primary); font-size: 16px; }
|
||
.card p { color: var(--text-secondary); font-size: 14px; margin: 0; }
|
||
.card .shortcut {
|
||
display: inline-block;
|
||
background: var(--bg-elevated);
|
||
border: 1px solid var(--border);
|
||
border-radius: 4px;
|
||
padding: 2px 8px;
|
||
font-family: 'SF Mono', Monaco, monospace;
|
||
font-size: 12px;
|
||
color: var(--color-primary);
|
||
margin: 2px 2px;
|
||
}
|
||
|
||
.verdict {
|
||
background: var(--bg-container);
|
||
border: 1px solid var(--border);
|
||
border-radius: var(--radius-md);
|
||
padding: 24px 32px;
|
||
margin: 20px 0;
|
||
box-shadow: var(--shadow-sm);
|
||
}
|
||
.verdict h4 {
|
||
color: var(--color-primary);
|
||
margin-bottom: 12px;
|
||
font-size: 16px;
|
||
background: linear-gradient(135deg, var(--color-primary), #722ED1);
|
||
-webkit-background-clip: text;
|
||
-webkit-text-fill-color: transparent;
|
||
background-clip: text;
|
||
}
|
||
.verdict p { color: var(--text-secondary); margin: 6px 0; font-size: 14px; }
|
||
.verdict strong { color: var(--text-primary); }
|
||
|
||
.tip-box {
|
||
background: var(--color-success-bg);
|
||
border: 1px solid var(--color-success-border);
|
||
border-radius: var(--radius-md);
|
||
padding: 20px 24px;
|
||
margin: 16px 0;
|
||
}
|
||
.tip-box h4 { color: var(--color-success); margin-bottom: 8px; font-size: 15px; }
|
||
.tip-box p { color: var(--text-secondary); font-size: 14px; margin: 4px 0; }
|
||
|
||
.warn-box {
|
||
background: var(--color-warning-bg);
|
||
border: 1px solid var(--color-warning-border);
|
||
border-radius: var(--radius-md);
|
||
padding: 20px 24px;
|
||
margin: 16px 0;
|
||
}
|
||
.warn-box h4 { color: var(--color-warning); margin-bottom: 8px; font-size: 15px; }
|
||
.warn-box p { color: var(--text-secondary); font-size: 14px; margin: 4px 0; }
|
||
|
||
.danger-box {
|
||
background: var(--color-error-bg);
|
||
border: 1px solid var(--color-error-border);
|
||
border-radius: var(--radius-md);
|
||
padding: 20px 24px;
|
||
margin: 16px 0;
|
||
}
|
||
.danger-box h4 { color: var(--color-error); margin-bottom: 8px; font-size: 15px; }
|
||
.danger-box p { color: var(--text-secondary); font-size: 14px; margin: 4px 0; }
|
||
|
||
.arch-pipeline {
|
||
display: flex;
|
||
flex-wrap: wrap;
|
||
gap: 8px;
|
||
align-items: center;
|
||
margin: 16px 0;
|
||
}
|
||
.arch-step {
|
||
background: var(--bg-container);
|
||
border: 1px solid var(--border);
|
||
border-radius: var(--radius-sm);
|
||
padding: 8px 16px;
|
||
font-size: 13px;
|
||
font-family: 'SF Mono', 'Menlo', monospace;
|
||
color: var(--color-primary);
|
||
}
|
||
.arch-step small { display: block; font-size: 11px; color: var(--text-tertiary); margin-top: 2px; }
|
||
.arch-arrow { color: var(--text-tertiary); font-size: 1.1rem; }
|
||
|
||
.tag {
|
||
display: inline-block;
|
||
padding: 2px 10px;
|
||
border-radius: 12px;
|
||
font-size: 12px;
|
||
font-weight: 600;
|
||
margin-right: 4px;
|
||
}
|
||
.tag-core { background: var(--color-primary-bg); color: var(--color-primary); border: 1px solid var(--color-primary); }
|
||
.tag-adv { background: #F9F0FF; color: #722ED1; border: 1px solid #D3ADF7; }
|
||
.tag-expert { background: var(--color-warning-bg); color: var(--color-warning); border: 1px solid var(--color-warning); }
|
||
|
||
ul, ol { margin-left: 20px; }
|
||
li { margin: 4px 0; color: var(--text-secondary); font-size: 14px; }
|
||
p { color: var(--text-secondary); font-size: 14px; margin: 8px 0; }
|
||
a { color: var(--color-primary); }
|
||
|
||
.footer {
|
||
text-align: center;
|
||
padding: 24px 0;
|
||
color: var(--text-tertiary);
|
||
font-size: 13px;
|
||
border-top: 1px solid var(--border);
|
||
margin-top: 20px;
|
||
}
|
||
|
||
@media (max-width: 992px) {
|
||
:root { --sidebar-w: 220px; }
|
||
.main { padding: 24px 20px 48px; }
|
||
}
|
||
@media (max-width: 768px) {
|
||
.sidebar { display: none; }
|
||
.main { margin-left: 0; }
|
||
.card-grid { grid-template-columns: 1fr; }
|
||
table { font-size: 13px; }
|
||
th, td { padding: 8px 10px; }
|
||
section { margin: 32px 0; }
|
||
}
|
||
</style>
|
||
</head>
|
||
<body>
|
||
|
||
<header class="header">
|
||
<h1>Claude Code 工程师使用指南</h1>
|
||
<span class="version">v2.1 · 2026-04-29</span>
|
||
</header>
|
||
|
||
<aside class="sidebar">
|
||
<div class="toc-label">目录</div>
|
||
<nav>
|
||
<ol>
|
||
<li><a href="#quickstart">快速上手</a></li>
|
||
<li><a href="#commands">斜杠命令全览</a></li>
|
||
<li><a href="#permissions">权限模式</a></li>
|
||
<li><a href="#shortcuts">键盘快捷键</a></li>
|
||
<li><a href="#directory">.claude 目录结构</a></li>
|
||
<li><a href="#claudemd">CLAUDE.md 配置</a></li>
|
||
<li><a href="#memory">项目记忆系统</a></li>
|
||
<li><a href="#hooks">Hooks 自动化</a></li>
|
||
<li><a href="#mcp">MCP 服务集成</a></li>
|
||
<li><a href="#agents">Agent 与 Teams</a></li>
|
||
<li><a href="#planmode">Plan Mode 规划模式</a></li>
|
||
<li><a href="#skills">Skills 技能系统</a></li>
|
||
<li><a href="#settings">Settings 配置详解</a></li>
|
||
<li><a href="#workflow">开发工作流最佳实践</a></li>
|
||
<li><a href="#context">上下文管理策略</a></li>
|
||
<li><a href="#git">Git 工作流集成</a></li>
|
||
<li><a href="#security">安全与权限</a></li>
|
||
<li><a href="#perf">性能优化</a></li>
|
||
<li><a href="#loop">Loop 与定时任务</a></li>
|
||
<li><a href="#faq">常见问题</a></li>
|
||
</ol>
|
||
</nav>
|
||
</aside>
|
||
|
||
<main class="main">
|
||
|
||
<!-- 1. Quick Start -->
|
||
<section id="quickstart">
|
||
<h2>1. 快速上手</h2>
|
||
|
||
<h3>1.1 启动 Claude Code</h3>
|
||
<pre><code># 在项目目录下启动
|
||
cd ~/projects/my-project
|
||
claude
|
||
|
||
# 指定提示词启动
|
||
claude "帮我实现一个用户认证模块"
|
||
|
||
# 带系统提示词启动
|
||
claude --system "你是一个资深 Go 工程师"
|
||
|
||
# 无头模式（CI/CD）
|
||
claude --print "运行测试并报告结果"</code></pre>
|
||
|
||
<h3>1.2 核心工作循环</h3>
|
||
<div class="arch-pipeline">
|
||
<span class="arch-step">输入需求</span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">Claude 读取代码</span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">Claude 提出方案</span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">审批工具调用</span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">Claude 执行修改</span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">验证结果</span>
|
||
</div>
|
||
|
||
<h3>1.3 首次使用推荐</h3>
|
||
<div class="card-grid">
|
||
<div class="card">
|
||
<h4>第一步：初始化项目</h4>
|
||
<p>运行 <code>/init</code> 生成 <code>CLAUDE.md</code>，让 Claude 理解项目结构、编码规范和架构约定。</p>
|
||
</div>
|
||
<div class="card">
|
||
<h4>第二步：确认权限</h4>
|
||
<p>使用 <code>Shift+Tab</code> 切换到合适的权限模式。新手推荐 Default 模式，每次操作前确认。</p>
|
||
</div>
|
||
<div class="card">
|
||
<h4>第三步：描述任务</h4>
|
||
<p>用自然语言描述需求，包含关键上下文："在 X 文件中添加 Y 功能，参考 Z 模块的风格"。</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="tip-box">
|
||
<h4>提示：让 Claude 自主探索</h4>
|
||
<p>对于不熟悉的代码库，先让 Claude 自己阅读相关文件，而不是直接给出修改方案。说"先看看相关代码"比直接给出修改指令更有效。</p>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- 2. Slash Commands -->
|
||
<section id="commands">
|
||
<h2>2. 斜杠命令全览</h2>
|
||
|
||
<h3>2.1 核心命令</h3>
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>命令</th><th>功能</th><th>使用场景</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><code>/help</code></td><td>显示帮助信息和可用命令</td><td>随时查看当前可用的命令和插件</td></tr>
|
||
<tr><td><code>/config</code></td><td>打开配置 UI</td><td>快速修改主题、模型、字体等设置</td></tr>
|
||
<tr><td><code>/compact</code></td><td>压缩对话上下文</td><td>长对话后释放上下文窗口，保留关键信息</td></tr>
|
||
<tr><td><code>/clear</code></td><td>清空对话历史</td><td>开始全新任务，重置对话</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>2.2 代码与项目命令</h3>
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>命令</th><th>功能</th><th>使用场景</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><code>/init</code></td><td>初始化项目，生成 CLAUDE.md</td><td>首次在新项目中使用，建立项目上下文</td></tr>
|
||
<tr><td><code>/review</code></td><td>审查当前分支的待提交变更</td><td>提交前自查代码质量</td></tr>
|
||
<tr><td><code>/security-review</code></td><td>安全审查待提交变更</td><td>合并前检查 SQL 注入、XSS 等安全问题</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>2.3 工作流命令</h3>
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>命令</th><th>功能</th><th>使用场景</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><code>/plan</code></td><td>进入规划模式</td><td>复杂任务前，先拆分步骤再实施</td></tr>
|
||
<tr><td><code>/btw</code></td><td>上下文提问不打断当前工作</td><td>边干活边问细节，不偏离主线</td></tr>
|
||
<tr><td><code>/loop <interval> <cmd></code></td><td>按间隔循环执行</td><td>监控构建状态、轮询部署进度</td></tr>
|
||
<tr><td><code>/permissions</code></td><td>查看/修改权限设置</td><td>管理工具权限白名单</td></tr>
|
||
<tr><td><code>/plugin</code></td><td>管理插件</td><td>安装/卸载自定义命令、技能、MCP 服务</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="tip-box">
|
||
<h4>提示：自定义斜杠命令</h4>
|
||
<p>在 <code>.claude/commands/</code> 目录下创建 <code>.md</code> 文件即可定义自定义斜杠命令。也可通过 Agent SDK 编程创建复杂命令。</p>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- 3. Permissions -->
|
||
<section id="permissions">
|
||
<h2>3. 权限模式</h2>
|
||
|
||
<p>Claude Code 提供 5 种权限模式，控制工具执行前的审批行为：</p>
|
||
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>模式</th><th>行为</th><th>推荐场景</th></tr></thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><strong>Auto（自动）</strong></td>
|
||
<td>Claude 自动执行，分类器模型在后台审查操作</td>
|
||
<td>高信任度场景，成熟的代码库</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Default（默认/安全）</strong></td>
|
||
<td>潜在危险操作（写文件、Shell 命令）需确认</td>
|
||
<td>日常开发，推荐作为默认模式</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Plan（规划）</td>
|
||
<td>实施前必须先规划</td>
|
||
<td>架构变更、重构</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Custom（自定义）</td>
|
||
<td>通过 settings.json 定义自定义规则</td>
|
||
<td>团队有特定规范时</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Manual（手动）</td>
|
||
<td>每个操作都需要显式批准</td>
|
||
<td>最高安全要求场景</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>3.1 切换模式</h3>
|
||
<ul>
|
||
<li><strong>快捷键</strong>：<span class="shortcut">Shift+Tab</span> 快速切换</li>
|
||
<li><strong>命令</strong>：<code>/permissions</code> 查看当前设置</li>
|
||
<li><strong>配置</strong>：<code>settings.json</code> 中设置 <code>permissions.defaultMode</code></li>
|
||
</ul>
|
||
|
||
<h3>3.2 工具级权限白名单</h3>
|
||
<p>在 <code>.claude/settings.json</code> 中为常用只读操作配置白名单，减少审批提示：</p>
|
||
<pre><code>{
|
||
"permissions": {
|
||
"allow": [
|
||
"Bash(git status:*)",
|
||
"Bash(ls:*)",
|
||
"Bash(find:*)",
|
||
"Bash(grep:*)"
|
||
]
|
||
}
|
||
}</code></pre>
|
||
|
||
<div class="warn-box">
|
||
<h4>注意</h4>
|
||
<p>只读操作（git status、ls、grep）可以安全加入白名单。写操作（rm、git reset）永远不要加入白名单，除非你完全信任自动化流程。</p>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- 4. Keyboard Shortcuts -->
|
||
<section id="shortcuts">
|
||
<h2>4. 键盘快捷键</h2>
|
||
|
||
<h3>4.1 会话控制</h3>
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>快捷键</th><th>功能</th><th>说明</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><span class="shortcut">Ctrl+C</span></td><td>中断当前操作</td><td>停止 Claude 的执行</td></tr>
|
||
<tr><td><span class="shortcut">Esc Esc</span></td><td>回退/撤销</td><td>回退 Claude 的上一次响应</td></tr>
|
||
<tr><td><span class="shortcut">Ctrl+B</span></td><td>后台运行</td><td>将长时间命令放入后台</td></tr>
|
||
<tr><td><span class="shortcut">Shift+Enter</span></td><td>多行输入</td><td>在提示框中输入换行</td></tr>
|
||
<tr><td><span class="shortcut">↑/↓</span></td><td>历史导航</td><td>浏览之前输入的命令</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>4.2 权限与配置</h3>
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>快捷键</th><th>功能</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><span class="shortcut">Shift+Tab</span></td><td>循环切换权限模式</td></tr>
|
||
<tr><td><span class="shortcut">Tab</span></td><td>自动补全/确认</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>4.3 自定义快捷键</h3>
|
||
<p>在 <code>~/.claude/keybindings.json</code> 中自定义快捷键，支持 50+ 内置操作和 17 个不同的上下文：</p>
|
||
<pre><code>{
|
||
"bindings": [
|
||
{
|
||
"keys": ["ctrl+s"],
|
||
"action": "submit",
|
||
"context": "prompt"
|
||
}
|
||
]
|
||
}</code></pre>
|
||
|
||
<div class="tip-box">
|
||
<h4>提示</h4>
|
||
<p>运行 <code>/keybindings-help</code> 获取自定义快捷键的配置帮助。</p>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- 5. .claude Directory -->
|
||
<section id="directory">
|
||
<h2>5. .claude 目录结构</h2>
|
||
|
||
<p><code>.claude/</code> 目录是 Claude Code 的项目控制中心，包含 5 个子系统配置：</p>
|
||
|
||
<pre><code>.claude/
|
||
├── CLAUDE.md # 项目指令（自动加载到系统提示）
|
||
├── settings.json # 项目级设置和权限（提交到 git）
|
||
├── settings.local.json # 本地设置（不提交到 git）
|
||
├── keybindings.json # 自定义键盘快捷键
|
||
├── agents/ # 自定义 Agent 定义
|
||
│ └── researcher.json
|
||
├── skills/ # 自定义技能定义
|
||
│ └── deploy-skill.json
|
||
├── memory/ # 持久化记忆文件
|
||
│ ├── MEMORY.md # 记忆索引
|
||
│ ├── user_preferences.md
|
||
│ └── project_context.md
|
||
├── rules/ # 详细规则文件
|
||
│ ├── coding-standards.md
|
||
│ └── testing-policy.md
|
||
├── commands/ # 自定义斜杠命令
|
||
│ └── deploy.md
|
||
└── plugins/ # 插件配置</code></pre>
|
||
|
||
<h3>5.1 用户级 vs 项目级</h3>
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>层级</th><th>路径</th><th>说明</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><strong>用户级</strong></td><td><code>~/.claude/</code></td><td>对所有项目生效，包含全局设置、技能、团队配置</td></tr>
|
||
<tr><td><strong>项目级</strong></td><td><code>.claude/</code></td><td>仅对当前项目生效，可提交到 git 与团队共享</td></tr>
|
||
<tr><td><strong>本地级</strong></td><td><code>.claude/settings.local.json</code></td><td>仅对当前项目生效，不提交到 git</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>5.2 配置加载优先级</h3>
|
||
<div class="arch-pipeline">
|
||
<span class="arch-step">settings.local.json<br><small>最高优先级</small></span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">settings.json<br><small>项目级</small></span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">~/.claude/settings.json<br><small>用户级</small></span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">managed-settings.json<br><small>管理员托管</small></span>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- 6. CLAUDE.md -->
|
||
<section id="claudemd">
|
||
<h2>6. CLAUDE.md 配置</h2>
|
||
|
||
<p><code>CLAUDE.md</code> 是 Claude Code 的项目 README，启动时自动加载并注入系统提示。</p>
|
||
|
||
<h3>6.1 最佳实践：路由文件模式</h3>
|
||
<p>保持 <code>CLAUDE.md</code> 精简（< 150 行），作为路由文件指向 <code>.claude/rules/*.md</code> 中的详细规则：</p>
|
||
|
||
<pre><code># CLAUDE.md
|
||
|
||
## 项目概览
|
||
全栈 Web 应用，前端 React + TypeScript，后端 Node.js + PostgreSQL
|
||
|
||
## 技术栈
|
||
- 前端: React 18, TypeScript, TailwindCSS
|
||
- 后端: Node.js, Express, Prisma ORM
|
||
- 数据库: PostgreSQL 15
|
||
- 测试: Jest + Playwright
|
||
|
||
## 编码规范
|
||
- 前端组件使用函数式 + Hooks
|
||
- API 响应统一为 { data, error } 格式
|
||
- 数据库迁移使用 Prisma migrate
|
||
|
||
## 详细规则
|
||
- 代码规范: [.claude/rules/coding-standards.md](.claude/rules/coding-standards.md)
|
||
- 测试策略: [.claude/rules/testing-policy.md](.claude/rules/testing-policy.md)
|
||
- 部署流程: [.claude/rules/deployment.md](.claude/rules/deployment.md)</code></pre>
|
||
|
||
<h3>6.2 层级结构</h3>
|
||
<p>CLAUDE.md 支持多层级文件，高层级覆盖低层级：</p>
|
||
<div class="arch-pipeline">
|
||
<span class="arch-step">~/.claude/CLAUDE.md<br><small>全局</small></span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">CLAUDE.md (项目根目录)<br><small>项目</small></span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">src/CLAUDE.md<br><small>目录级</small></span>
|
||
</div>
|
||
|
||
<div class="warn-box">
|
||
<h4>避免</h4>
|
||
<p>不要把 <code>CLAUDE.md</code> 写成知识库。它是上下文注入，不是文档。详细规则拆到 <code>.claude/rules/</code> 中，只保留关键信息在 CLAUDE.md。</p>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- 7. Memory -->
|
||
<section id="memory">
|
||
<h2>7. 项目记忆系统</h2>
|
||
|
||
<p>Claude Code 通过 <code>.claude/memory/</code> 目录实现跨会话持久记忆，分为四种类型：</p>
|
||
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>类型</th><th>用途</th><th>示例</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><strong>user</strong></td><td>用户的角色、偏好、知识背景</td><td>"用户是后端工程师，偏好接口优先开发"</td></tr>
|
||
<tr><td><strong>feedback</strong></td><td>用户对 Claude 行为的指导</td><td>"不要在集成测试中 mock 数据库"</td></tr>
|
||
<tr><td><strong>project</strong><td>项目进行中工作的上下文</td><td>"2026-04-29 后开始非关键合并冻结"</td></tr>
|
||
<tr><td><strong>reference</strong></td><td>外部系统资源的位置</td><td>"Grafana 看板: grafana.internal/d/api-latency"</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>7.1 记忆文件格式</h3>
|
||
<pre><code>---
|
||
name: no-db-mocking
|
||
description: 集成测试必须使用真实数据库
|
||
type: feedback
|
||
---
|
||
|
||
集成测试必须使用真实数据库，不能 mock。
|
||
**Why:** 上季度 mock/prod 差异导致迁移失败但测试通过。
|
||
**How to apply:** 所有 integration test 使用真实 PostgreSQL 实例。</code></pre>
|
||
|
||
<h3>7.2 MEMORY.md 索引</h3>
|
||
<p><code>MEMORY.md</code> 是记忆文件的索引，Claude 启动时加载此文件：</p>
|
||
<pre><code># 记忆索引
|
||
|
||
- [数据库测试偏好](no-db-mocking.md) — 集成测试不用 mock
|
||
- [用户背景](user-role.md) — 资深 Go 工程师，新项目学 Rust
|
||
- [合并冻结](merge-freeze.md) — 2026-04-29 后非关键 PR 暂停</code></pre>
|
||
|
||
<div class="tip-box">
|
||
<h4>记忆存储位置</h4>
|
||
<p>记忆文件位于 <code>/home/zdh/.claude/projects/-home-zdh-projects/memory/</code>，自动创建和维护。Claude 会根据对话内容自动保存和更新记忆。</p>
|
||
</div>
|
||
|
||
<h3>7.3 什么不该存</h3>
|
||
<ul>
|
||
<li>代码模式、架构、文件路径 — 可以从代码本身读取</li>
|
||
<li>Git 历史、谁改了什么 — <code>git log</code> 是权威来源</li>
|
||
<li>调试方案 — 修复已经在代码里了</li>
|
||
<li>临时任务细节 — 只在当前会话中相关</li>
|
||
</ul>
|
||
</section>
|
||
|
||
<!-- 8. Hooks -->
|
||
<section id="hooks">
|
||
<h2>8. Hooks 自动化</h2>
|
||
|
||
<p>Hooks 是 Claude Code 的自动化机制，在特定事件触发时执行 Shell 命令。由 Claude Code harness 执行，不是 LLM 本身。</p>
|
||
|
||
<h3>8.1 配置方式</h3>
|
||
<p>在 <code>settings.json</code> 或 <code>settings.local.json</code> 中配置：</p>
|
||
<pre><code>{
|
||
"hooks": {
|
||
"PostToolUse": {
|
||
"Write": "npx eslint --fix",
|
||
"Edit": "npx prettier --write"
|
||
},
|
||
"PreToolUse": {
|
||
"Bash": "echo '即将执行: $CLAUDE_TOOL_INPUT'"
|
||
},
|
||
"Notification": {
|
||
"PostCommand": "say 'Claude 完成'"
|
||
}
|
||
}
|
||
}</code></pre>
|
||
|
||
<h3>8.2 可用 Hook 事件</h3>
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>Hook</th><th>触发时机</th><th>典型用途</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><code>PostToolUse.Write</code></td><td>每次写文件后</td><td>自动 lint/format</td></tr>
|
||
<tr><td><code>PostToolUse.Edit</code></td><td>每次编辑文件后</td><td>自动格式化</td></tr>
|
||
<tr><td><code>PostToolUse.Bash</code></td><td>每次执行 Bash 命令后</td><td>验证结果</td></tr>
|
||
<tr><td><code>PreToolUse.*</code></td><td>工具执行前</td><td>注入上下文、安全检查</td></tr>
|
||
<tr><td><code>Notification.PostCommand</code></td><td>Claude 完成回复后</td><td>桌面通知</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="warn-box">
|
||
<h4>重要</h4>
|
||
<p>自动化行为（"每次编辑后 X"、"从现在开始当 Y 时"）必须通过 settings.json 中的 hooks 配置，不能通过记忆或偏好设置。Claude Code harness 执行 hooks，不是 LLM。</p>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- 9. MCP -->
|
||
<section id="mcp">
|
||
<h2>9. MCP 服务集成</h2>
|
||
|
||
<p>MCP（Model Context Protocol）让 Claude Code 连接外部工具：文件系统、API、数据库、开发工具等。</p>
|
||
|
||
<h3>9.1 安装范围</h3>
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>范围</th><th>配置位置</th><th>说明</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><strong>本地</strong></td><td><code>~/.claude/mcp.json</code></td><td>仅当前用户可用</td></tr>
|
||
<tr><td><strong>项目</strong></td><td><code>.claude/mcp.json</code></td><td>团队共享，提交到 git</td></tr>
|
||
<tr><td><strong>用户</strong></td><td><code>~/.claude/mcp.json</code></td><td>所有项目可用</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>9.2 配置示例</h3>
|
||
<pre><code>{
|
||
"mcpServers": {
|
||
"github": {
|
||
"command": "npx",
|
||
"args": ["-y", "@modelcontextprotocol/server-github"],
|
||
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
|
||
},
|
||
"filesystem": {
|
||
"command": "npx",
|
||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/zdh/projects"]
|
||
},
|
||
"postgres": {
|
||
"command": "npx",
|
||
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
|
||
}
|
||
}
|
||
}</code></pre>
|
||
|
||
<h3>9.3 常用 MCP 服务</h3>
|
||
<div class="card-grid">
|
||
<div class="card">
|
||
<h4>GitHub</h4>
|
||
<p>PR 管理、Issue 跟踪、仓库操作。适合代码审查和 CI/CD 集成。</p>
|
||
</div>
|
||
<div class="card">
|
||
<h4>Filesystem</h4>
|
||
<p>受限文件系统访问，限制在指定目录下操作。</p>
|
||
</div>
|
||
<div class="card">
|
||
<h4>Database</h4>
|
||
<p>PostgreSQL、MySQL 等数据库直接查询和 schema 探索。</p>
|
||
</div>
|
||
<div class="card">
|
||
<h4>Jira/Confluence</h4>
|
||
<p>项目管理平台集成，查询 issue 和文档。</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="tip-box">
|
||
<h4>提示</h4>
|
||
<p>目前有 25+ 官方 MCP 服务可用。通过 <code>/plugin</code> 命令可以浏览和安装更多社区插件。</p>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- 10. Agents & Teams -->
|
||
<section id="agents">
|
||
<h2>10. Agent 与 Teams</h2>
|
||
|
||
<h3>10.1 Agent 系统</h3>
|
||
<p>Claude Code 支持派生专用 Agent 处理复杂任务。每种 Agent 有不同的工具集和能力：</p>
|
||
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>Agent 类型</th><th>能力</th><th>适用场景</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><strong>general-purpose</strong></td><td>全部工具</td><td>通用复杂任务</td></tr>
|
||
<tr><td><strong>Explore</strong></td><td>只读搜索</td><td>快速定位代码、文件搜索</td></tr>
|
||
<tr><td><strong>Plan</strong></td><td>只读分析</td><td>设计实现方案、架构分析</td></tr>
|
||
<tr><td><strong>claude-code-guide</strong></td><td>搜索+文档</td><td>Claude Code 功能查询</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>10.2 Teams 团队协作</h3>
|
||
<p>多个 Agent 组成 Team，共享任务列表，并行工作：</p>
|
||
<pre><code># Team 工作流程
|
||
1. TeamCreate — 创建团队和任务列表
|
||
2. TaskCreate — 创建结构化任务
|
||
3. Agent + team_name — 派生 Agent 加入团队
|
||
4. TaskUpdate + owner — 分配任务给 Agent
|
||
5. Agent 完成任务 → TaskUpdate + status:completed
|
||
6. 所有任务完成后 SendMessage 关闭团队</code></pre>
|
||
|
||
<h3>10.3 自定义 Agent</h3>
|
||
<p>在 <code>.claude/agents/</code> 中定义自定义 Agent：</p>
|
||
<pre><code>// .claude/agents/frontend-reviewer.json
|
||
{
|
||
"name": "frontend-reviewer",
|
||
"description": "审查前端代码变更",
|
||
"model": "sonnet",
|
||
"instructions": "审查 React 组件代码，关注性能、可访问性和最佳实践。"
|
||
}</code></pre>
|
||
</section>
|
||
|
||
<!-- 11. Plan Mode -->
|
||
<section id="planmode">
|
||
<h2>11. Plan Mode 规划模式</h2>
|
||
|
||
<p>规划模式是处理复杂变更的最佳实践：先设计方案，再实施。</p>
|
||
|
||
<h3>11.1 何时使用</h3>
|
||
<ul>
|
||
<li>新功能实现，涉及多个文件和模块</li>
|
||
<li>重构现有代码，可能影响多个功能</li>
|
||
<li>架构决策，需要在多个方案中选择</li>
|
||
<li>不确定的需求，需要先探索代码库</li>
|
||
</ul>
|
||
|
||
<h3>11.2 工作流</h3>
|
||
<div class="arch-pipeline">
|
||
<span class="arch-step">/plan 进入规划</span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">探索代码库</span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">设计方案</span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">用户审批</span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">ExitPlanMode 退出</span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">实施变更</span>
|
||
</div>
|
||
|
||
<div class="tip-box">
|
||
<h4>推荐</h4>
|
||
<p>对于涉及 3 个以上文件的变更，总是先使用规划模式。这比直接修改后回退要高效得多。</p>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- 12. Skills -->
|
||
<section id="skills">
|
||
<h2>12. Skills 技能系统</h2>
|
||
|
||
<p>Skills 是可复用工作流包，通过 <code>/技能名</code> 调用，组合提示词、指令和自定义工具。</p>
|
||
|
||
<h3>12.1 可用技能</h3>
|
||
<p>技能列表在会话中通过系统提醒消息显示。分为两类：</p>
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>类型</th><th>路径</th><th>说明</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><strong>项目级</strong></td><td><code>.claude/skills/</code></td><td>仅当前项目可用，随代码共享</td></tr>
|
||
<tr><td><strong>用户级</strong></td><td><code>~/.claude/skills/</code></td><td>所有项目可用</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>12.2 调用方式</h3>
|
||
<pre><code># 调用内置技能
|
||
/review
|
||
/security-review
|
||
/init
|
||
|
||
# 调用自定义技能（需要显式调用）
|
||
/project-dir-manager
|
||
/remote-sync
|
||
/loop 5m /status</code></pre>
|
||
|
||
<div class="warn-box">
|
||
<h4>注意</h4>
|
||
<p>不要猜测技能名称。只调用系统提醒列表中显示的技能，或用户明确输入 <code>/技能名</code> 的技能。</p>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- 13. Settings -->
|
||
<section id="settings">
|
||
<h2>13. Settings 配置详解</h2>
|
||
|
||
<h3>13.1 settings.json 核心字段</h3>
|
||
<p>v2.1 支持 60+ 设置项和 175+ 配置选项：</p>
|
||
<pre><code>{
|
||
"permissions": {
|
||
"defaultMode": "default"
|
||
},
|
||
"hooks": {
|
||
"PostToolUse": {
|
||
"Write": "npx eslint --fix"
|
||
}
|
||
},
|
||
"env": {
|
||
"NODE_ENV": "development"
|
||
},
|
||
"mcpServers": {
|
||
"github": {
|
||
"command": "npx",
|
||
"args": ["-y", "@modelcontextprotocol/server-github"]
|
||
}
|
||
},
|
||
"allowedTools": ["Bash", "Read", "Edit", "Write"],
|
||
"disabledTools": ["Agent"],
|
||
"model": "opus"
|
||
}</code></pre>
|
||
|
||
<h3>13.2 配置层次</h3>
|
||
<div class="arch-pipeline">
|
||
<span class="arch-step">settings.local.json<br><small>不提交 git</small></span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">settings.json<br><small>提交 git</small></span><span class="arch-arrow">→</span>
|
||
<span class="arch-step">~/.claude/settings.json<br><small>用户全局</small></span>
|
||
</div>
|
||
|
||
<div class="tip-box">
|
||
<h4>提示</h4>
|
||
<p>个人偏好设置（API key、本地路径）放在 <code>settings.local.json</code> 中，避免提交到 git。团队共享配置放在 <code>settings.json</code> 中。</p>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- 14. Workflow Best Practices -->
|
||
<section id="workflow">
|
||
<h2>14. 开发工作流最佳实践</h2>
|
||
|
||
<h3>14.1 高效提示词编写</h3>
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>差</th><th>好</th><th>原因</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>"修复 bug"</td><td>"修复 src/auth.py 第 42 行的空指针异常，当 user_id 为 None 时"</td><td>具体、可操作</td></tr>
|
||
<tr><td>"优化性能"</td><td>"api/handler.go 的 ListUsers 函数响应超 500ms，数据库查询占 80%，优化它"</td><td>有数据支撑</td></tr>
|
||
<tr><td>"加个登录功能"</td><td>"在 src/auth/ 中添加 OAuth2 登录，参考 src/oauth/ 中已有的 Google 集成风格"</td><td>有上下文</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>14.2 推荐开发流程</h3>
|
||
<div class="verdict">
|
||
<h4>标准开发流程</h4>
|
||
<p><strong>1. 理解代码</strong> — 让 Claude 先读取相关文件，说"先看看这个模块的代码"</p>
|
||
<p><strong>2. 制定方案</strong> — 复杂变更用 <code>/plan</code>，让 Claude 展示方案并审批</p>
|
||
<p><strong>3. 实施变更</strong> — 审批后 Claude 实施，使用 Default 权限模式逐步确认</p>
|
||
<p><strong>4. 验证结果</strong> — 运行测试 <code>npm test</code> / <code>go test</code> / <code>pytest</code></p>
|
||
<p><strong>5. 代码审查</strong> — 运行 <code>/review</code> 自查，再 <code>/security-review</code></p>
|
||
<p><strong>6. 提交变更</strong> — 让 Claude 创建 commit，遵循项目风格</p>
|
||
</div>
|
||
|
||
<h3>14.3 多文件开发策略</h3>
|
||
<ul>
|
||
<li><strong>独立变更</strong>：并行派生多个 Agent 同时处理</li>
|
||
<li><strong>依赖变更</strong>：按顺序处理，先改底层再改上层</li>
|
||
<li><strong>大规模重构</strong>：使用 Plan Mode 拆分步骤，逐步实施</li>
|
||
</ul>
|
||
|
||
<h3>14.4 测试驱动开发</h3>
|
||
<pre><code># 推荐：先让 Claude 写测试，再实现功能
|
||
"为 UserService.createUser 写单元测试，包含正常路径和异常路径"
|
||
# 然后：运行测试看失败
|
||
"现在实现 createUser 让测试通过"
|
||
# 最后：确认所有测试通过
|
||
"运行测试确认全部通过"</code></pre>
|
||
</section>
|
||
|
||
<!-- 15. Context Management -->
|
||
<section id="context">
|
||
<h2>15. 上下文管理策略</h2>
|
||
|
||
<h3>15.1 上下文窗口管理</h3>
|
||
<p>Claude Code 有有限的上下文窗口。长对话会逐渐填满，需要管理：</p>
|
||
<ul>
|
||
<li><strong>自动压缩</strong>：Claude Code 在接近限制时自动压缩早期消息</li>
|
||
<li><strong>手动压缩</strong>：使用 <code>/compact</code> 主动压缩，保留关键信息</li>
|
||
<li><strong>新对话</strong>：使用 <code>/clear</code> 开始全新对话</li>
|
||
</ul>
|
||
|
||
<h3>15.2 何时压缩</h3>
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>场景</th><th>建议</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>对话超过 50 轮</td><td>运行 <code>/compact</code> 或 <code>/clear</code></td></tr>
|
||
<tr><td>完成一个任务，开始下一个</td><td><code>/clear</code> 开始新对话</td></tr>
|
||
<tr><td>Claude 开始遗忘早期上下文</td><td><code>/compact</code> 压缩</td></tr>
|
||
<tr><td>需要 Claude 记住特定信息</td><td>保存到 <code>.claude/memory/</code> 持久记忆</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>15.3 信息留存策略</h3>
|
||
<p>对话中的关键信息通过以下方式留存：</p>
|
||
<ul>
|
||
<li><strong>CLAUDE.md</strong>：项目结构和规范，每次启动自动加载</li>
|
||
<li><strong>记忆系统</strong>：用户偏好、项目决策、外部资源位置</li>
|
||
<li><strong>代码本身</strong>：最重要的信息是代码本身，不需要额外记忆</li>
|
||
</ul>
|
||
</section>
|
||
|
||
<!-- 16. Git Integration -->
|
||
<section id="git">
|
||
<h2>16. Git 工作流集成</h2>
|
||
|
||
<h3>16.1 Claude Code 的 Git 操作</h3>
|
||
<p>Claude Code 可以直接执行 Git 命令，但遵循安全协议：</p>
|
||
<ul>
|
||
<li>不跳过 hook（<code>--no-verify</code>）</li>
|
||
<li>不强制 push（<code>--force</code>），除非用户明确要求</li>
|
||
<li>不修改 git config</li>
|
||
<li>创建新 commit 而非 amend，除非用户明确要求</li>
|
||
</ul>
|
||
|
||
<h3>16.2 推荐的 Git 工作流</h3>
|
||
<pre><code># 1. 让 Claude 查看当前状态
|
||
"看看当前 git 状态"
|
||
|
||
# 2. 让 Claude 创建 commit
|
||
"把刚才的变更提交，写一个简洁的 commit message"
|
||
|
||
# 3. 审查 commit
|
||
"看看这个 commit 包含了什么"
|
||
|
||
# 4. 创建 PR（需要 gh CLI）
|
||
"创建一个 PR，标题简短，正文用 bullet points 描述变更"
|
||
|
||
# 5. 处理冲突
|
||
"这个分支和 main 有冲突，帮我解决"</code></pre>
|
||
|
||
<h3>16.3 Worktree 隔离</h3>
|
||
<p>对于并行开发，使用 Git Worktree 隔离不同分支的工作：</p>
|
||
<ul>
|
||
<li>Claude Code 内置 <code>EnterWorktree</code> 支持</li>
|
||
<li>自动创建临时分支和工作目录</li>
|
||
<li>完成后自动清理或保留</li>
|
||
</ul>
|
||
</section>
|
||
|
||
<!-- 17. Security -->
|
||
<section id="security">
|
||
<h2>17. 安全与权限</h2>
|
||
|
||
<h3>17.1 Claude Code 安全原则</h3>
|
||
<ul>
|
||
<li><strong>默认安全</strong>：Default 模式下，危险操作需要确认</li>
|
||
<li><strong>不执行不可信代码</strong>：Claude 不会直接运行从网上复制的代码</li>
|
||
<li><strong>不暴露密钥</strong>：Claude 避免将敏感文件（.env、credentials）提交到 git</li>
|
||
<li><strong>OWASP 安全</strong>：Claude 避免引入 XSS、SQL 注入等常见漏洞</li>
|
||
</ul>
|
||
|
||
<h3>17.2 安全审查</h3>
|
||
<p>在合并变更前运行 <code>/security-review</code>，检查：</p>
|
||
<ul>
|
||
<li>SQL 注入和参数化查询</li>
|
||
<li>XSS 和输入验证</li>
|
||
<li>认证和授权绕过</li>
|
||
<li>敏感数据泄露</li>
|
||
<li>依赖安全问题</li>
|
||
</ul>
|
||
|
||
<div class="danger-box">
|
||
<h4>重要提醒</h4>
|
||
<p>Claude Code 仅辅助授权安全测试、防御安全、CTF 竞赛和教育场景。拒绝拒绝技术、DoS 攻击、大规模攻击、供应链妥协或恶意检测规避的请求。</p>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- 18. Performance -->
|
||
<section id="perf">
|
||
<h2>18. 性能优化</h2>
|
||
|
||
<h3>18.1 响应速度</h3>
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>优化</th><th>方法</th><th>效果</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>减少上下文</td><td>定期 <code>/compact</code>，精简 CLAUDE.md</td><td>减少 token 处理时间</td></tr>
|
||
<tr><td>并行 Agent</td><td>独立任务同时派生多个 Agent</td><td>减少串行等待</td></tr>
|
||
<tr><td>权限白名单</td><td>只读操作加入 settings.json allow</td><td>减少审批等待</td></tr>
|
||
<tr><td>后台任务</td><td>长时间命令 <code>run_in_background: true</code></td><td>不阻塞 Claude 响应</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>18.2 避免的反模式</h3>
|
||
<ul>
|
||
<li><strong>不要 sleep 轮询</strong>：用 <code>run_in_background</code> + 等待完成</li>
|
||
<li><strong>不要重复搜索</strong>：Agent 的 Explore 模式结果复用</li>
|
||
<li><strong>不要全量扫描</strong>：<code>find</code> 从 <code>.</code> 开始，不扫描整个文件系统</li>
|
||
<li><strong>不要过度抽象</strong>：3 行相似代码优于半成品的抽象</li>
|
||
</ul>
|
||
|
||
<div class="tip-box">
|
||
<h4>提示</h4>
|
||
<p>使用 Fast Mode（<code>/fast</code>）获取更快的响应速度，使用 Claude Opus 4.6 模型快速输出（不会降级到小模型）。</p>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- 19. Loop & Scheduled Tasks -->
|
||
<section id="loop">
|
||
<h2>19. Loop 与定时任务</h2>
|
||
|
||
<h3>19.1 Loop 循环执行</h3>
|
||
<p><code>/loop</code> 命令按固定间隔重复执行提示或命令：</p>
|
||
<pre><code># 每 5 分钟检查构建状态
|
||
/loop 5m 检查 CI 构建是否完成
|
||
|
||
# 每 10 分钟运行测试
|
||
/loop 10m /review
|
||
|
||
# 默认间隔 10 分钟
|
||
/loop /status</code></pre>
|
||
|
||
<h3>19.2 ScheduleWakeup 定时唤醒</h3>
|
||
<p>更精细的定时控制，支持一次性或重复任务：</p>
|
||
<ul>
|
||
<li><strong>一次性</strong>：60s-3600s 范围内，适合"1 小时后提醒我"</li>
|
||
<li><strong>重复</strong>：最小 60s，最大 3600s（1 小时）</li>
|
||
<li><strong>自动过期</strong>：重复任务 7 天后自动过期</li>
|
||
</ul>
|
||
|
||
<h3>19.3 Cron 调度</h3>
|
||
<p>通过 <code>CronCreate</code> 工具支持标准 5 字段 cron 表达式：</p>
|
||
<pre><code># 每个工作日 9am
|
||
"0 9 * * 1-5"
|
||
|
||
# 每 5 分钟
|
||
"*/5 * * * *"
|
||
|
||
# 今天下午 2:30 一次性
|
||
"30 14 29 4 *" (recurring: false)</code></pre>
|
||
|
||
<div class="warn-box">
|
||
<h4>注意</h4>
|
||
<p>定时任务只在 Claude Code 会话活跃期间执行。Cron 任务可以通过 <code>durable: true</code> 持久化到 <code>.claude/scheduled_tasks.json</code>，重启后恢复。</p>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- 20. FAQ -->
|
||
<section id="faq">
|
||
<h2>20. 常见问题</h2>
|
||
|
||
<h3>Q: Claude Code 和 Claude API 有什么区别？</h3>
|
||
<p>Claude Code 是 CLI 工具，内置文件操作、Shell 执行、Git 集成。Claude API 是原始 API，需要自己编写所有集成代码。</p>
|
||
|
||
<h3>Q: Claude Code 能看到我整个代码库吗？</h3>
|
||
<p>不会。Claude Code 按需读取文件，不会自动扫描整个代码库。对于大项目，建议让 Claude 搜索相关文件而不是读取全部。</p>
|
||
|
||
<h3>Q: 如何保护敏感信息？</h3>
|
||
<p>Claude Code 会避免将 .env、credentials.json 等敏感文件提交到 git。但最好的实践是确保这些文件已在 .gitignore 中。</p>
|
||
|
||
<h3>Q: Claude 会记住什么？</h3>
|
||
<p>对话历史在当前会话中保留。跨会话记忆通过 <code>.claude/memory/</code> 持久化。CLAUDE.md 每次启动时自动加载。</p>
|
||
|
||
<h3>Q: 如何让 Claude 更自主地工作？</h3>
|
||
<p>切换到 Auto 权限模式，为常用只读操作配置权限白名单，使用 Hooks 实现自动化后处理。</p>
|
||
|
||
<h3>Q: Claude Code 能用来做 CI/CD 吗？</h3>
|
||
<p>可以。使用 <code>--print</code> 标志在无头模式下运行，或结合 GitHub Actions 等 CI 系统。</p>
|
||
|
||
<h3>Q: 自定义斜杠命令怎么创建？</h3>
|
||
<p>在 <code>.claude/commands/</code> 目录下创建 <code>.md</code> 文件，或通过 Agent SDK 编程创建复杂命令。</p>
|
||
|
||
<h3>Q: 如何选择模型？</h3>
|
||
<p>通过 <code>/config</code> 或在 settings.json 中设置 <code>"model": "opus"</code> / <code>"model": "sonnet"</code> / <code>"model": "haiku"</code>。Opus 最强，Sonnet 平衡，Haiku 最快。</p>
|
||
</section>
|
||
|
||
<div class="footer">
|
||
<p>Claude Code 工程师使用指南 · v2.1 · 基于最新版本文档 · 2026-04-29</p>
|
||
</div>
|
||
|
||
</main>
|
||
|
||
<script>
|
||
const links = document.querySelectorAll('.sidebar nav a');
|
||
const sections = document.querySelectorAll('.main section, .main .footer');
|
||
|
||
function setActive() {
|
||
let current = '';
|
||
sections.forEach(s => {
|
||
if (s.getBoundingClientRect().top < 120) current = s.id;
|
||
});
|
||
links.forEach(a => {
|
||
a.classList.toggle('active', a.getAttribute('href') === '#' + current);
|
||
});
|
||
}
|
||
|
||
links.forEach(a => {
|
||
a.addEventListener('click', e => {
|
||
e.preventDefault();
|
||
const target = document.querySelector(a.getAttribute('href'));
|
||
if (target) target.scrollIntoView();
|
||
});
|
||
});
|
||
|
||
window.addEventListener('scroll', setActive, { passive: true });
|
||
setActive();
|
||
</script>
|
||
|
||
</body>
|
||
</html> |