ljwx-children/QUICKSTART.md

🚀 Gold Template 快速入门指南

🎯 5 分钟上手

第 1 步：创建你的项目 (30 秒)

# 方法 1: 使用 GitHub 模板
# 在 GitHub 上点击 "Use this template" 按钮

# 方法 2: 克隆仓库
git clone https://github.com/yourusername/gold-template.git my-awesome-project
cd my-awesome-project

第 2 步：一键设置 (2 分钟)

# 运行设置脚本
./scripts/setup.sh

# 脚本会自动：
# ✅ 检查 Python 版本
# ✅ 创建虚拟环境
# ✅ 安装所有依赖
# ✅ 配置环境文件
# ✅ 初始化数据库
# ✅ 设置 Git hooks

第 3 步：配置环境 (1 分钟)

# 编辑 .env 文件
nano .env  # 或使用你喜欢的编辑器

# 必需配置：
# - SECRET_KEY: 生成一个安全的密钥
# - GITHUB_TOKEN: (可选) 用于 GitHub API 访问

第 4 步：启动开发 (1 分钟)

# 启动开发服务器
./scripts/dev.sh

# 服务器启动后：
# 🌐 应用: http://localhost:8000
# 📖 API 文档: http://localhost:8000/docs

第 5 步：开始使用 Claude Code (30 秒)

# 在新终端中启动 Claude Code
claude

# 在 Claude Code 中输入：
"帮我分析这个项目的结构和功能"

🎨 你的第一个功能

让我们用 Claude Code 添加一个简单的 API 端点：

与 Claude 对话

你：我想添加一个 /health 健康检查端点。
    应该返回服务器状态和版本信息。

Claude：我来帮你实现...
    [Claude 会创建代码和测试]

你：看起来不错！请帮我运行测试验证一下。

Claude：[运行测试并报告结果]

你：完美！请帮我创建一个 commit。

Claude：[创建规范的 commit]

验证功能

# 访问健康检查端点
curl http://localhost:8000/health

# 应该返回类似：
{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-12-29T12:00:00Z"
}

📋 典型开发流程

场景 1: 添加新功能

# 1. 创建 Issue
gh issue create --template claude-assisted-task.md

# 2. 创建分支
git checkout -b feature/user-profile

# 3. 使用 Claude Code 开发
claude
> "实现用户个人资料功能"
> [Claude 引导你完成设计、实现、测试]

# 4. 运行测试
./scripts/test.sh

# 5. 提交代码
git add .
git commit -m "feat: add user profile endpoint"

# 6. 创建 PR
gh pr create --fill

# 7. 等待审查和合并

场景 2: 修复 Bug

# 1. 创建 Bug Issue
gh issue create --template bug-report.md

# 2. 创建修复分支
git checkout -b fix/login-error

# 3. 使用 Claude 调试
claude
> "帮我分析这个登录错误：[错误信息]"
> [Claude 帮你找到根因并修复]

# 4. 验证修复
./scripts/test.sh

# 5. 提交和创建 PR
git commit -m "fix: resolve login validation error"
gh pr create --fill

场景 3: 代码审查

# 作为审查者
# 1. 查看 PR
gh pr checkout 123

# 2. 使用 Claude 辅助审查
claude
> "请审查这个 PR 的变更，重点关注安全性和性能"

# 3. 提供反馈
gh pr review 123 --comment -b "LGTM! 建议..."

# 4. 批准或请求修改
gh pr review 123 --approve

🔧 常用命令速查

项目管理

# 查看所有 issues
gh issue list

# 查看所有 PRs
gh pr list

# 查看项目状态
gh project list

# 查看工作流运行
gh workflow list

开发

# 启动开发服务器
./scripts/dev.sh

# 运行测试
./scripts/test.sh

# 代码格式化
black .

# 代码检查
flake8 .

# 类型检查
mypy src/

Git 操作

# 创建新分支
git checkout -b feature/name

# 提交变更
git add .
git commit -m "feat: description"

# 推送分支
git push -u origin feature/name

# 同步主分支
git checkout main
git pull origin main

Claude Code

# 启动 Claude Code
claude

# 使用自定义 skill
/project-init "new-project"
/code-review "src/"

# 退出
exit

🎯 下一步

了解更多

1. 阅读完整文档

   • Claude 开发工作流
   • GitHub 集成最佳实践
   • CLAUDE.md

2. 配置 GitHub Projects

   # 创建项目看板
   gh project create --owner @me --title "My Project"
   

3. 设置 CI/CD

   • 检查 .github/workflows/ 中的工作流
   • 配置必要的 secrets
   • 启用 GitHub Actions

4. 自定义模板

   • 修改项目结构适应你的需求
   • 添加自定义 skills
   • 调整 GitHub 模板

推荐实践

✅ 每天

• 使用 Claude Code 辅助开发
• 频繁提交代码
• 运行测试验证

✅ 每周

• 审查项目看板
• 更新文档
• 代码审查

✅ 每月

• 回顾开发指标
• 优化工作流
• 团队知识分享

💡 提示和技巧

Claude Code 使用技巧

1. 提供清晰的上下文

   ❌ "修复这个 bug"
   ✅ "backend/auth.py:45 行抛出 KeyError，
       在用户登录时如果 token 过期会发生。
       请帮我添加错误处理。"
   

2. 迭代式开发

   第一步："分析现有的认证系统"
   第二步："设计添加 OAuth 支持的方案"
   第三步："实现 Google OAuth"
   第四步："编写测试"
   

3. 利用对话历史

   "基于我们刚才讨论的设计，现在实现数据库部分"
   

GitHub 使用技巧

1. 使用标签组织

   • 为 Issue 添加有意义的标签
   • 使用项目看板跟踪进度

2. 自动化工作流

   • 利用 GitHub Actions
   • 设置自动化规则

3. 代码审查

   • 及时审查 PR
   • 提供建设性反馈
   • 使用 Claude 辅助审查

❓ 常见问题

Q: 如何更新模板？

# 添加上游仓库
git remote add template https://github.com/yourusername/gold-template.git

# 获取更新
git fetch template
git merge template/main

# 解决冲突（如有）

Q: 如何自定义 Claude skills？

查看 .claude/skills/project-init/ 作为示例，然后：

1. 创建新目录：.claude/skills/my-skill/
2. 添加 skill.json 配置
3. 添加 run.sh 脚本
4. 在 Claude Code 中使用：/my-skill

Q: 如何集成到现有项目？

# 复制需要的部分到你的项目
cp -r gold-template/.github your-project/
cp -r gold-template/.claude your-project/
cp -r gold-template/docs your-project/
cp -r gold-template/scripts your-project/

# 根据需要调整

Q: 在哪里获取帮助？

• 📖 查看 完整文档
• 🐛 报告问题
• 💬 讨论区
• 🤖 询问 Claude Code

🎉 开始你的旅程

恭喜！你已经准备好使用 Gold Template 和 Claude Code 进行高效开发了。

记住：

• 🤖 充分利用 Claude Code
• 📋 使用 GitHub Projects 管理任务
• ✅ 始终编写测试
• 📚 保持文档更新
• 🚀 享受开发的乐趣！

---

Happy Coding! 🚀

如有问题，随时查阅文档或向 Claude Code 提问！