SkillGap：打造AI驱动的职业助理

I’m happy to help translate the article, but I’ll need the text you’d like translated. Could you please paste the content (excluding the source line you already provided) here? Once I have it, I’ll translate it into Simplified Chinese while preserving the original formatting and markdown.

问题

职位描述很难阅读。它们篇幅冗长，充斥着流行词汇，真的很难判断自己是否符合要求。大多数人要么：

• 把自己说服放弃本可以得到的工作，或者
• 申请自己还没有准备好的职位。

没有一种快速、诚实的方式可以将你的技能与职位实际需求进行对比。这就是我们想要解决的问题。

我们的解决方案

SkillGap 为您完成比较。

1. 粘贴职位描述到应用中。
2. 应用 检查它与您已保存的技能档案的匹配情况。
3. 您将收到 匹配分数、将您的技能划分为三组的细分（已有 / 缺失 / 加分），以及 个性化 AI 学习路线图。

您将获得清晰、可执行的计划，而不是猜测。随着学习并更新您的档案，结果也会随之提升。

团队分工

我们使用的 AI 工具

拆分: Claude Web 用于规划，Antigravity 用于构建。

核心架构

身份验证

SkillGap 的所有功能都依赖于识别用户身份。

• 实现了基于 JWT 的身份验证（注册、登录、登出、受保护的路由）。
• 密码在写入数据库前会进行 加盐和哈希 处理。
• 每个受保护的请求都会验证 JWT 令牌。

首先构建此功能，因为所有其他功能都依赖它。

技能档案 CRUD

在身份验证之上，我们为技能档案实现了完整的 CRUD 操作。

• 用户可以随时 添加、编辑和删除 技能。
• 更改会立即持久化，因此每次新的分析都会使用最新的档案版本。

数据库设计

• SQLAlchemy 架构涵盖用户、技能档案和分析历史。
• history 表 让用户能够回顾过去的分析，并随时间跟踪匹配分数的提升。
• Alembic 负责迁移；每一次模式更改都会生成可审查、测试并干净回滚的迁移文件。

Matching Engine

This is the core algorithm of the product.

1. Input: Job description + user’s skill profile.
2. Process: Compare both against a curated list of tech skills.
3. Output:
   • Have: Skills the user possesses that the job wants.
   • Missing: Skills the job wants that the user does not have.
   • Bonus: Skills the user brings that the job did not ask for.

• Keyword normalization maps variations (e.g., “React”, “ReactJS”, “React.js”) to a single entry.
• Vocabulary covers frontend, backend, infrastructure, and data tools.
• Engine lives in its own module, separate from auth and profile modules → easy unit testing and future extension.

Visual Feedback

• Animated SVG ring shows the match score:
  • Green → strong match
  • Yellow → partial match
  • Red → significant gap
• Ring draws progressively on page load, giving a “calculation” feel.
• Below the ring, a three‑column view lists the exact skills behind the score.

Design & Planning with Claude Web

在编写任何代码之前，Jing 使用 Claude Web 以自然语言梳理项目设计。对话帮助她：

• 确定核心用户流程。
• 决定先构建哪些功能。
• 揭示未解答的 PRD 问题（例如，处理未知技能、为新用户提供入职指引）。

提前做出这些决定，后期大幅减少了调试时间。

AI 驱动的学习路线图

1. Extraction engine 识别缺失的技能。
2. FastAPI 后端 将这些技能 + 原始职位描述发送给 Claude API。
3. Claude 返回一个 结构化的 JSON 路线图：

{
  "steps": [
    {
      "skill": "Docker",
      "resources": ["Docker Docs", "Docker for Beginners (Udemy)"],
      "estimated_time": "4h",
      "explanation": "Docker is required for containerizing the microservices mentioned in the JD."
    }
    // …
  ]
}

4. React 前端 解析 JSON 并渲染一行 卡片，每个主题对应一张卡片，形成易于阅读、可操作的计划。

不是通用的链接列表——而是围绕特定岗位需求构建的个性化、排序好的计划。

测试策略

提取引擎（确定性）

• 严格 TDD：在实现之前编写测试。
• server/tests/ 中的每个模块都有对应的 test_.py。
• CI 流水线阻止任何导致 pytest 覆盖率低于 80 % 的合并。

Claude 路线图（非确定性）

• 构建了 AI 评估测试套件，对每个响应在三个维度上进行评分：
  1. 相关性 – 资源是否匹配缺失的技能？
  2. 具体性 – 步骤是否具体而非模糊？
  3. 完整性 – 是否覆盖了所有缺失的技能？
• 评分结果输入 评估仪表板。

安全挑战

1. 客户端分数伪造 – 比赛分数在 React 端计算，导致可以被篡改。
2. （原文摘录中省略的第二个问题 – 为完整性保留占位符）。

两项问题均已通过将关键计算迁移至后端并强制严格的令牌验证来解决。

摘要

SkillGap 结合了 强大的身份验证、动态技能档案管理、智能匹配引擎以及 AI 生成的学习路线图，为求职者提供清晰、可操作的路径，帮助他们实现想要的职位。通过利用 Claude Web 进行规划，Antigravity 进行实现，团队交付了一个统一的产品，并通过 TDD 和专门的 AI 评估框架保持了高代码质量。

概述

我们在原始实现中发现并修复了两个关键问题：

1. 客户端分数操控 – 前端向 FastAPI 后端发送计算后的分数，导致用户在存储之前可以篡改该值。
   Solution: 将计算完全移到服务器端，忽略任何客户端提供的分数。

2. 未处理的 SQLAlchemy 异常 – 数据库错误导致返回 500 响应，暴露完整堆栈跟踪，泄露内部实现细节。
   Solution: 添加全局错误处理器，在服务器端记录完整的回溯，并向客户端返回干净、安全的错误信息。

两个问题均在代码审查阶段被发现并在投入生产前修复。

UI 改进

• 响应式体验： 添加了专注的 UI 迭代，使应用感觉更流畅，尤其是在 Claude API 调用期间（需要几秒钟）。
• 错位动画： 使用 framer‑motion 让技能列和路线图卡片依次动画，呈现渐进式揭示，而不是突兀一次性展示。
• 骨架 UI： 当 Claude API 调用进行中时，结果面板显示与最终内容形状相匹配的骨架占位符，降低感知等待时间。

设计工作流程

1. Sketch → Claude Web → Production

   • Liuyi 用手绘的仪表盘草图开始。
   • 该草图被输入到 Claude Web，它生成了包含组件建议和布局推理的详细线框图。
   • 该线框图成为生产实现的设计规范，使用 IDE 中的 Antigravity 构建。

   结果： 在编写任何 React 代码之前拥有具体的参考，使得设计猜测更少，重写次数也更少。

CI/CD 流水线

• 每个拉取请求在合并前会运行一个多阶段的 GitHub Actions 流水线：

  1. Lint – ruff（Python）和 ESLint（JS/TS）
  2. 安全扫描
  3. Pytest
  4. 构建

• 覆盖率门槛: 后端测试覆盖率必须保持 ≥ 80 %；否则流水线失败，拉取请求被阻止。

• 密钥管理: API 密钥、JWT 密钥和数据库连接字符串仅存放在 GitHub Secrets 中，并在运行时注入。

• 部署: 当 main 分支更新时，应用会自动部署到 Render。

这强制执行的质量标准如果仅存在于文档中，往往容易被忽视。

AI生成路线图的自动评估

1. Claude生成路线图后，进行一次第二次LLM调用来评估它。
2. 评估者会收到该路线图、原始的缺失技能列表以及职位描述，然后使用固定的评分标准对响应的相关性、具体性和完整性进行打分。

为什么？ 使用AI评估AI输出提供了一种可扩展的方式来测试非确定性结果，能够提供一致的、结构化的分数，便于随时间跟踪。人工审查仍然有价值，但此自动化提供了量化的质量信号。

• Liuyi在真实测试数据上运行了完整的评估套件，并将结果反馈给Claude Web。
• Claude Web生成了一个评估网页产物：对所有分数的简洁汇总，并附有解释高分和低分的备注。

该页面有两个用途：

• 为Claude API集成提供具体的质量信号。
• 生成可共享的文档，明确展示AI输出的测量方式及其结果。

Tooling: Claude Web vs. Antigravity

Mixing the two roles would have slowed us down. Copy‑pasting code from a chat window adds friction, and using a conversational tool for implementation loses the iterative loop that surfaces better decisions. Keeping each tool in its optimal role made both more effective.

工具对比：Claude Web 与 Antigravity

将两者角色混合会减慢我们的进度。 从聊天窗口复制粘贴代码会增加摩擦，而使用对话工具进行实现会失去迭代循环，从而错失更好的决策。让每个工具发挥其最佳作用，使两者都更有效。

未来技术升级

1. Semantic skill matching – 用 sentence‑transformer embeddings 替代关键词提取。当前引擎仅匹配精确关键词；语义嵌入能够识别“component‑based UI development”对应 React，从而扩展对普通英文职位描述的覆盖范围。
2. Resume parsing – 允许用户上传简历并自动构建其技能画像。
3. Reverse analysis mode – 让雇主能够将候选人的画像与职位发布进行对比检查。

对 SkillGap 的反思

• 起源： 最初是课堂项目，现在成为展示作品。
• 模块化架构： 使得各自独立工作而不相互干扰代码。
• 共享约定： .antigravityrules 文件在冲突出现前就规范了约定。
• AI 分工： 用 Claude Web 进行规划，用 Antigravity 实现，提升速度且不牺牲输出质量。

关键要点： AI 工具可以加速稳健的工程流程，但它们并不能取代严谨的开发实践。

项目概述

SkillGap — Tech Stack Skill Gap Analyzer
一个帮助求职者从职位描述中识别技能差距的网页应用。

• 粘贴职位描述 → 查看匹配分数 → 获取 AI 生成的学习路线图。

团队

• Jing Ng
• Liuyi Yang

技术栈

功能

• 职位描述解析与技能差距评分
• AI 生成的学习路线图
• 带动画 UI 的交互式仪表盘
• 自动化 CI/CD，包含代码检查、漏洞扫描、测试及覆盖率强制
• 安全的密钥管理与 Render 部署

截图

• 登录页
• 注册页
• 个人资料设置页
• 主仪表盘 – 技能匹配分析

系统架构

（此处插入架构图）

用户提交职位描述时的请求流程

1. 用户操作 – 用户将职位描述粘贴到 UI 中。
2. 服务器处理 –
   • 服务器将职位描述与用户保存的技能档案进行比较。
   • 计算匹配分数。
   • 将差距信息发送给 Claude AI。
3. AI 生成 – Claude AI 生成个性化学习计划，以弥补识别出的技能差距。
4. 结果 – 学习计划返回前端并显示给用户。

涉及的技术：前端（React），后端（FastAPI），数据库，Claude API

项目结构

SkillGap/
├── client/           # React 前端 (Vite, Tailwind, Zustand)
├── server/           # FastAPI 后端
│   ├── tests/        # pytest 测试套件
│   └── …            # 其他后端模块
└── …                # 其他顶层文件 (README, .gitignore 等)

View on GitHub (replace # with the actual repository URL)