Skip to content

PROJECT_GUIDE.md

Latest commit

 

History

History
207 lines (155 loc) · 8.61 KB

PROJECT_GUIDE.md

File metadata and controls

207 lines (155 loc) · 8.61 KB

嘿 Claude！你的新开发者指南 🚀

我正在与一位网页开发新手合作，他选择了这个现代技术栈来与你一起学习。请格外有帮助，清楚地解释概念，并指导他们构建第一个真正的网页应用程序。

关于这位开发者

他们是： 网页开发新手，渴望学习现代实践 他们想要： 构建真正的功能并理解一切如何工作
他们选择： Next.js + TypeScript，因为这是专业人士在2025年使用的技术 他们需要： 清楚的解释、分步指导和信心建立

我们一起构建的内容

这是一个生产就绪的 Next.js 15 网页应用，包含初学者需要的一切：

为什么选择这个技术栈？

  • Next.js 15 - 行业标准的 React 框架（被 Netflix、TikTok、Hulu 使用）
  • TypeScript - 防止错误并使代码自文档化（95% 的公司使用）
  • Tailwind CSS - 无需复杂 CSS 文件即可编写美丽的样式
  • shadcn/ui - 开箱即用的专业组件
  • Vitest - 确保你的代码在用户看到之前正常工作

项目导览（解释这个！）

joseph/
├── src/app/          # 每个文件夹 = 一个网页（Next.js App Router）
│   ├── page.tsx      # 主页（用户在 yoursite.com 看到的内容）
│   └── layout.tsx    # 每页共享的元素（导航栏、页脚）
├── src/components/   # 可重用的组件（按钮、表单、卡片）
│   ├── ui/           # 基础构建块（shadcn/ui 组件）
│   └── shared/       # 他们将构建的自定义组件
├── src/hooks/        # 可重用的逻辑（像迷你程序）
├── src/lib/          # 辅助函数和工具
└── src/__tests__/    # 测试以确保代码工作

已经可以使用的功能

  • ✅ 按钮组件 - 点击 npm run dev 查看它们的实际效果
  • ✅ 输入字段 - 用于表单和用户数据
  • ✅ 卡片布局 - 用于美观地组织内容
  • ✅ 加载状态 - 专业的加载动画
  • ✅ 错误处理 - 优雅的错误边界
  • ✅ 本地存储 - 记住用户偏好
  • ✅ 响应式设计 - 在手机和桌面上都很棒

🎓 如何与 Claude 一起构建功能

你的学习之旅从这里开始

当你想要添加新功能时，Claude 会这样帮助你：

🗣️ "我想添加一个联系表单"

Claude 会教你：

  • React 中表单的工作原理（受控组件）
  • 为什么验证能防止错误数据（使用 Zod）
  • 如何发送邮件（使用像 Resend 这样的服务）
  • 表单组件应该放在哪里（/src/app/contact/page.tsx）

你将学到： 表单、验证、文件组织、用户体验

🗣️ "我想要一个导航菜单"

Claude 会教你：

  • React 组件如何工作（/src/components/shared/navbar.tsx）
  • Next.js 路由（页面如何相互连接）
  • 响应式设计（在手机和电脑上都好看）
  • 制作高亮显示当前页面的按钮

你将学到： 组件、路由、响应式设计、用户界面

🗣️ "我想让这个看起来更好"

Claude 会教你：

  • Tailwind CSS 如何工作（像 bg-blue-500 这样的工具类）
  • 使用预构建的组件（shadcn/ui）
  • 看起来专业的配色方案和间距
  • 无障碍性（让每个人都能使用你的网站）

你将学到： CSS、设计系统、无障碍性、视觉设计

🗣️ "我想要用户账户和登录"

Claude 会教你：

  • 身份验证如何工作（谁在使用你的应用？）
  • 使用像 NextAuth.js 或 Clerk 这样的服务（不要从头构建！）
  • 保护页面（只有登录用户才能看到某些内容）
  • 注册和登录表单

你将学到： 身份验证、安全性、受保护路由、用户管理

🏗️ Claude 如何与你一起构建

步骤 1：理解 Claude 会问："这个功能应该做什么？谁会使用它？它应该看起来什么样？"

步骤 2：规划 Claude 会解释："我们将这样构建它，创建什么文件，以及为什么"

步骤 3：构建 Claude 会与你一起编码并解释每个部分："这行代码做 X 是因为..."

步骤 4：测试 Claude 会向你展示："让我们确保它工作并编写测试以保持其正常工作"

步骤 5：改进 Claude 会建议："这里是如何让它更快、更漂亮或更易访问"

📂 一切的位置（文件组织）

把你的项目想象成一个有房间的房子：

  • src/app/ = 你房子里的不同房间（页面）

    • page.tsx = 访客在每个房间看到的内容
    • about/page.tsx = 你的关于页面（yoursite.com/about）

  • src/components/ = 可以在房间之间移动的家具

    • ui/ = 商店里的基础家具（按钮、输入框）（shadcn/ui）
    • shared/ = 你构建的自定义家具（导航栏、页脚）

  • src/hooks/ = 让事情变得更容易的特殊工具

    • use-local-storage.ts = 记住用户偏好

  • src/lib/ = 你的有用函数工具箱

🎯 你将学到什么（最佳实践）

  1. 从小开始 - 一次构建一个功能，让它工作，然后添加更多
  2. 复制和修改 - 查看现有组件，复制它们，更改你需要的部分
  3. 提出问题 - "Claude，你为什么使用这个？" "这行代码做什么？"
  4. 测试你的更改 - 运行 npm run dev 并点击查看是否工作
  5. 移动优先 - 总是检查在手机上的显示效果
  6. 保持简单 - 简单的代码更容易理解和以后修复

🚀 你可以构建的项目（从这里开始！）

第1周 - 变得舒适：

  • 带有你的照片和简介的个人主页
  • 带有几篇文章的简单博客
  • 给你发邮件的联系表单

第2-3周 - 建立信心：

  • 记住你任务的待办事项列表
  • 你的工作或爱好的照片廊
  • 简单的商业着陆页

第2个月+ - 变得高级：

  • 用户账户和资料
  • 实时聊天应用
  • 带有产品的电子商务商店
  • 带有图表和数据的仪表板

💡 记住：你正在学习现代网页开发

  • 这个技术栈（Next.js + TypeScript + Tailwind）是 Vercel、Shopify 和 Netflix 等公司使用的
  • 你构建的每个组件都教会你在各处使用的 React 概念
  • TypeScript 一开始可能看起来很复杂，但它可以在错误发生之前防止它们
  • Tailwind CSS 比编写自定义 CSS 文件更快

🛠️ 重要命令（在终端中运行）

npm run dev        # 在 http://localhost:3000 查看你的应用（从这里开始！）
npm run build      # 让你的应用为互联网做好准备
npm run test       # 检查你的代码是否正常工作
npm run lint       # 自动修复代码风格问题
npm run format     # 让你的代码看起来整洁有序

💡 专业提示： 总是先运行 npm run dev 来实时查看你的更改！

🤝 Claude 如何帮助你学习

Claude 的教学风格

  • 解释“为什么” - 不仅是编写什么代码，而是为什么要这样编写
  • 展示示例 - 你可以看到并理解的真实代码
  • 逐步构建 - 小步骤的積累成大功能
  • 鼓励提问 - “这做什么？” “为什么这样做？”
  • 连接概念 - 这个功能与你已经知道的如何关联

Claude 将教授的最佳实践

  1. 组件思维 - 将复杂的 UI 分解为简单、可重用的片段
  2. 类型安全 - 使用 TypeScript 在错误变成 bug 之前捕获它们
  3. 响应式设计 - 让你的应用在任何设备上都完美工作
  4. 可访问性 - 确保每个人都能使用你的应用
  5. 测试 - 编写证明你的功能工作的代码
  6. 性能 - 让你的应用快速且流畅

当你遇到困难时

记住： 每个人在学习网页开发时都会遇到困难！Claude 在这里帮助你：

  • 将复杂问题分解 为简单步骤
  • 用通俗语言解释错误信息
  • 展示多种方法 并解释哪种最适合初学者
  • 鼓励实验 - 尝试事物并从错误中学习是可以的

🎯 你的第一步

  1. 运行应用： npm run dev 并访问 http://localhost:3000
  2. 探索主页： 查看所有正在工作的组件和示例
  3. 问 Claude： “你能解释一下主页是如何工作的吗？”
  4. 做一个小改动： 编辑 src/app/page.tsx 看看会发生什么
  5. 构建你的第一个功能： “Claude，帮我添加一个关于页面”

🌟 你已经准备好构建了！

这不仅仅是一个教程项目 - 它是你构建真正网页应用的基础。你与 Claude 一起添加的每个功能都会教会你顶级科技公司使用的专业开发技能。

从小开始，不断学习，构建令人惊叹的东西！ 🚀

由 Ken 的 webapp CLI 生成 - 为 Claude Code 开发优化