立CLAUDE.md规矩，造首个密码工具

首页 › tutorials › 立CLAUDE.md规矩，造首个密码工具

概述

本教程面向零基础读者，目标只有一个：用最短路径把 Claude Code 装通、配好，并亲手带它造出第一个能跑、有测试、有 Git 记录的命令行项目——一个密码工具箱 pwkit。与传统"装完就用"教程不同，本文的核心是把 CLAUDE.md 项目记忆文件作为第一课：它会让你学会如何用一份"项目说明书"给 Claude 立下规矩，让它从第一次对话就懂你的技术栈、代码规范和验收标准。学完你能独立完成"安装→认证→立规矩→规划→实现→自检→提交"的完整闭环。

前置条件

一台 macOS 13+、Windows 10 1809+ 或 Ubuntu 20.04+ 的电脑，内存 4GB 以上
一个 Claude 订阅账号（Pro / Max / Team / Enterprise）或 Claude Console（API 预付额度）账号
能联网，且身处 Anthropic 支持的国家或地区
Python 3.10+（本教程的项目用它实现；若没有，让 Claude 帮你装）
不需要先学终端命令——遇到不懂的，直接在 Claude 里问

正文

步骤 1：选对安装方式，告别 Node 依赖

Claude Code 现在有四种官方安装方式。对零基础读者，强烈推荐原生安装（Native Install），因为它不依赖 Node.js，装完还会在后台自动更新，省去手动升级的烦恼。

在终端里根据系统粘贴对应命令：

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

另外三种方式作为补充：

方式	命令	是否自动更新	适用场景
原生安装（推荐）	`curl … install.sh \\| bash`	✅ 后台自动	零基础首选
Homebrew	`brew install --cask claude-code`	❌ 需手动 `brew upgrade`	已用 brew 管软件的 Mac 用户
WinGet	`winget install Anthropic.ClaudeCode`	❌ 需手动 `winget upgrade`	Windows 标准用户
npm	`npm install -g @anthropic-ai/claude-code`	❌	已装 Node 的开发者

预期结果：命令跑完后，终端输入 claude --version 能打印出版本号，说明安装成功。

常见问题： - Windows 上报 'irm' is not recognized：说明你在 CMD 里，应改用 CMD 那条命令；反之报 '&&' is not a valid statement separator 说明你在 PowerShell 里。 - curl 报 403 或 syntax error near unexpected token '<'：通常是网络代理或公司防火墙拦截，换用 npm 方式或检查代理设置即可。 - 装完找不到 claude 命令：原生安装会提示你把可执行文件路径加入 PATH，按提示复制那一行到你的 shell 配置文件（~/.zshrc 或 ~/.bashrc）再 source 一次。

步骤 2：首次登录，建立身份

在任意目录输入 claude 启动交互式会话，首次会自动弹出登录流程，引导你在浏览器里完成认证。支持 Pro/Max/Team/Enterprise 订阅号，也支持 Console 付费额度号，还支持 Amazon Bedrock、Google Cloud Agent Platform 等企业云通道。

登录一次后，凭据会安全保存在本地，之后无需重复登录。若要切换账号，在会话里输入 /login 即可。

预期结果：会话顶部出现版本号、当前模型、工作目录三行信息，下方是输入提示符，说明你已进入 Claude Code。

步骤 3：建立项目骨架，写下 CLAUDE.md 立规矩（核心）

这是本教程最重要的一步。Claude Code 在每次启动时会自动读取项目根目录的 CLAUDE.md，把它作为长期记忆注入上下文。这份文件就是你和 Claude 之间的"项目契约"——你把技术栈、代码规范、验收标准写进去，Claude 之后每次写代码都会自觉遵守，不需要你反复叮嘱。

先建好项目目录并进入：

mkdir pwkit && cd pwkit
claude

然后直接对 Claude 说第一句话：

在当前目录创建一个 Python 项目骨架：pwkit/ 放源码，tests/ 放测试，根目录建一个 CLAUDE.md。CLAUDE.md 的内容我接下来口述，你照写。

接着把下面这份"规矩"口述给它（你也可以直接用编辑器手写）：

# pwkit 项目说明

## 项目目标
命令行密码工具箱，提供「生成强密码」和「检查密码强度」两个子命令。

## 技术栈与约束
- Python 3.10+，仅用标准库，禁止引入任何第三方依赖
- 命令行解析用 argparse
- 随机数必须用 secrets 模块，禁止用 random（不安全）
- 所有面向用户的输出使用中文

## 代码规范
- 每个函数必须有类型注解和 docstring
- generate(length) 默认 16 位，必须包含大写、小写、数字、符号各至少一个
- score(password) 返回 0-4 的整数评分和中文说明（很弱/较弱/中等/较强/很强）

## 验收标准（给 Claude 的自检命令）
- 运行 `python -m pytest tests/` 必须 100% 通过
- 实现完成后，你必须自己跑一遍测试；若有失败，自动修复直到全绿，再结束任务

为什么这一步如此关键：初学者最常踩的坑，是每次对话都要重新告诉 Claude"用标准库""输出中文""跑一下测试"。有了 CLAUDE.md，这些规矩被固化下来，Claude 会在后续所有会话里自动遵守。它还会被纳入上下文缓存，长期使用更省钱。

步骤 4：用 Plan 模式先规划，再动手

Claude Code 的最佳实践是"先探索、再规划、再编码"。对零基础读者，最简单的做法是按 Shift+Tab 切到 Plan 模式（或输入 /plan）。在该模式下 Claude 只读不写，会先给你一份实施方案让你审阅。

切到 Plan 模式后输入：

根据 CLAUDE.md，规划 pwkit 的实现：列出要创建的文件、每个文件的职责、generate 和 score 的算法思路，以及测试用例。先不要写代码。

预期结果：Claude 会回一份分文件、分函数的方案，并标注它会怎么满足"每类字符至少一个"和"secrets 而非 random"这两条规矩。你确认无误后，按 Shift+Tab 切回默认模式准备实现。

常见问题： - 任务很小（比如改个错别字）就不必走 Plan 模式，直接让它改即可——规划本身有开销。 - 看到方案不满意，可以直接在同一轮对话里提修改意见，让它重出。

步骤 5：让 Claude 实现，并给它"自检手段"

切回默认模式后，把规划交给它执行，关键是把验收命令一起写进同一条指令：

按 CLAUDE.md 实现整个 pwkit。写完后运行 python -m pytest tests/，若有失败就读错误、改代码、重跑，直到全部通过。最后把测试输出贴给我看。

pwkit/__main__.py 最终大致长这样（Claude 会按你的 CLAUDE.md 生成）：

import argparse
import secrets
import string

def generate(length: int = 16) -> str:
    """生成包含大写、小写、数字、符号的强密码。"""
    pools = [string.ascii_uppercase, string.ascii_lowercase,
             string.digits, "!@#$%^&*"]
    chars = [secrets.choice(p) for p in pools]          # 每类至少一个
    all_chars = "".join(pools)
    chars += [secrets.choice(all_chars) for _ in range(length - len(pools))]
    secrets.SystemRandom().shuffle(chars)               # 打乱顺序
    return "".join(chars)

def score(password: str) -> tuple[int, str]:
    """返回 0-4 强度评分与中文说明。"""
    s = 0
    if len(password) >= 12: s += 1
    if any(c.isupper() for c in password) and any(c.islower() for c in password): s += 1
    if any(c.isdigit() for c in password): s += 1
    if any(c in "!@#$%^&*" for c in password): s += 1
    return s, ["很弱", "较弱", "中等", "较强", "很强"][s]

def main() -> None:
    p = argparse.ArgumentParser(prog="pwkit", description="密码工具箱")
    sub = p.add_subparsers(dest="cmd", required=True)
    g = sub.add_parser("gen", help="生成密码"); g.add_argument("length", type=int, nargs="?", default=16)
    c = sub.add_parser("check", help="检查强度"); c.add_argument("password")
    a = p.parse_args()
    if a.cmd == "gen": print(generate(a.length))
    elif a.cmd == "check":
        s, label = score(a.password); print(f"强度评分：{s}/4（{label}）")

if __name__ == "__main__":
    main()

测试文件 tests/test_pwkit.py：

from pwkit import __main__ as pw

def test_generate_length():
    assert len(pw.generate(20)) == 20

def test_generate_has_all_classes():
    pwd = pw.generate(16)
    assert any(c.isupper() for c in pwd)
    assert any(c.islower() for c in pwd)
    assert any(c.isdigit() for c in pwd)

def test_score_weak_and_strong():
    assert pw.score("abc")[0] == 0
    assert pw.score("Abcdefgh1!2")[0] == 4

预期结果：Claude 会展示要改动的文件、请求你批准，然后落盘；接着它自动 pytest，把绿色通过的输出贴出来。因为它读到了 CLAUDE.md 里"失败就修到全绿"的规矩，你不必盯着。

给 Claude 一个能跑出"通过/失败"的检查，是区分"你得盯着它"和"你能走开"的分水岭。

步骤 6：亲手验证，感受"自检闭环"

虽然 Claude 已自检，但你仍应亲自跑一次，确认它没有"看起来完成了"：

python -m pwkit gen 20        # 输出一段 20 位强密码
python -m pwkit check "123"   # 输出：强度评分：0/4（很弱）
python -m pwkit check "Abcdefgh1!2xyz"  # 输出：强度评分：4/4（很强）
python -m pytest tests/ -v    # 三条测试全绿

步骤 7：用 Git 留下第一笔记录

最后让 Claude 把成果提交进版本库，全程自然语言驱动：

初始化 git 仓库，把所有文件加入并提交，提交信息用中文，简明描述这次实现了密码生成和强度检查功能。

预期结果：Claude 会创建仓库、生成合理的中文提交信息并完成首次提交。

实战案例：把 pwkit 扩展成"泄露检测"工具

作为延伸练习，回到 Claude 维让它加一个 pwkit leak <password> 子命令：调用免费 Have I Been Pwned 的 Range API（k-anonymity，只传密码 SHA-1 的前 5 位，不泄露明文）检查密码是否在已知泄露库中。把这条新规矩追加进 CLAUDE.md：

## 新增约束（leak 子命令）
- 用 hashlib 算 SHA-1，只把前 5 位 hex 发给 https://api.pwnedpasswords.com/range/<前5位>
- 本地比对返回结果里是否含剩余哈希后缀，输出"未泄露"或"已在 N 次泄露中出现"
- 禁止把完整密码或完整哈希发到网络

因为规矩已写进 CLAUDE.md，Claude 会自动采用安全的 k-anonymity 做法，无需你额外强调。这就是 CLAUDE.md 的复利价值：规矩写一次，长期生效。

工作流程图

flowchart TD
    A[原生安装 claude.ai/install.sh] --> B[首次浏览器登录认证]
    B --> C[创建项目目录并 cd 进入]
    C --> D[撰写 CLAUDE.md 立下项目规矩]
    D --> E[Shift+Tab 进入 Plan 模式规划]
    E --> F{方案是否满意?}
    F -- 否 --> E
    F -- 是 --> G[切回默认模式实现]
    G --> H[Claude 自动跑 pytest 自检]
    H --> I{测试全绿?}
    I -- 否 --> G
    I -- 是 --> J[你亲自验证 CLI 输出]
    J --> K[Git 初始化并提交]
    K --> L[追加新规矩扩展功能]

训练营适用性评估

适用类型：零基础开发者入门营、AI 编程工具训练营第 1 天、"从 0 到 1 体验 Agent 编程"工作坊。也适合作为企业内训让传统工程师首次接触 AI 编程的破冰课。
教学时长：建议 90–120 分钟。其中安装与认证 20 分钟，CLAUDE.md 概念讲解与撰写 30 分钟，Plan 模式 + 实现 + 自检 40 分钟，Git 提交与拓展练习 20 分钟。
学员产出：每人带走一个可运行、有测试、有 Git 记录的密码工具 CLI，以及一份能复用到下一个项目的 CLAUDE.md 模板。
进阶衔接：本课掌握 CLAUDE.md 与验证闭环后，可顺接"自定义 Skill 开发""MCP 工具开发""Hooks 自动化"等高阶主题，规矩文件与自检思想会在后续课程中反复复用。

参考来源

Quickstart - Claude Code Docs — 官方八步快速上手指南，涵盖安装、登录、首次代码改动与常用命令
Best practices for Claude Code — 官方最佳实践，重点讲解上下文管理、Plan 模式四阶段与"给 Claude 验证手段"的闭环思想
Advanced setup - Claude Code Docs — 系统要求、原生/Homebrew/WinGet/npm 四种安装方式、自动更新与卸载详解
Claude Code Cheat Sheet (2.1.x) — 2026 版快捷键、斜杠命令、CLI 标志速查表，Opus 4.8 默认模型
Claude Code Tutorial for Beginners - Complete 2026 Guide — 第三方零基础完整教程，含 CLAUDE.md、自动记忆、Plan 模式与定价讲解

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

51学通信知识星球海报-扫码加入

概述