不想起名字

Appearance

用 Codex 和 Claude Code 两天做一个 Next.js + Supabase 导航站：NavSphere 项目复盘 ​

这两天我看了一个小而完整的项目：NavSphere。

项目在线地址也已经有了：

https://nav.myls.top/

它不是那种只有一个首页截图能看的"演示型项目"，而是一个已经具备完整使用链路的开发者导航站：

  • 前台导航首页
  • GitHub 登录
  • 后台管理
  • JSON 批量导入
  • Chrome 书签导入脚本
  • Supabase RLS 权限控制
  • 可直接接到 Vercel 部署

如果只看最终界面，会觉得这只是一个"收藏夹网站"。 但从工程角度看，它其实是一个很典型的 AI 时代小型全栈项目样本：

需求不算大，但链路完整，足够检验 Codex 和 Claude Code 到底能不能把一个项目从想法快速推进到可部署状态。

这篇文章就从几个角度来复盘它：

  • 用到了哪些技术
  • 项目是怎么组织的
  • 实际怎么部署
  • 如果用 Codex 和 Claude Code 做，速度大概有多快
  • 人工出力主要还剩下什么

先用一句话概括：

NavSphere 是一个面向开发者和团队内部工具场景的导航站。

它不是单纯展示一堆链接，而是把"公开导航"和"个人私有导航"放在同一个系统里：

  • 未登录用户可以看到公开分类和公开链接
  • 登录用户可以看到自己的私有分类和私有链接
  • 后台可以维护分类、链接、排序和导入
  • 分类支持路径式命名，例如 研发 / AI工具

这类项目非常适合做成一个轻量化内部产品，或者作为个人工作台的入口层。

这个项目用了哪些技术 ​

从仓库来看，NavSphere 的核心技术栈非常清晰：

  • Next.js 16
  • React 19
  • TypeScript
  • Tailwind CSS 4
  • Supabase Auth + Database
  • Vercel Analytics / Speed Insights

如果再细分一层，可以看到它是一个标准的 Next.js App Router + Supabase SSR 架构。

1. 前端层 ​

项目使用的是 Next.js App Router。 路由结构很直观：

  • app/page.tsx 负责前台导航首页
  • app/login 负责登录页
  • app/admin 负责后台页面
  • app/auth/callback/route.ts 负责 GitHub OAuth 回调
  • app/api/import 和 app/api/ai-import 负责导入接口

前台导航页并不是一个纯静态页面，它会在服务端读取导航数据，然后交给客户端壳组件做交互。

这里有几个做得比较顺手的点：

  • 用 useDeferredValue 和自定义 debounce 处理搜索
  • 用 IntersectionObserver 跟踪当前可见分类
  • 用 useTransition 处理后台跳转和搜索输入的过渡状态
  • 用 router.prefetch('/admin') 提前预取后台页面

也就是说，这不是"能跑就行"的 React 页面，而是已经开始用 React 19 的交互能力去优化体验了。

2. 数据层 ​

数据层是 Supabase PostgreSQL。

数据库里只有两张核心表：

  • categories
  • links

另外定义了一个枚举：

  • link_environment，值为 test 和 prod

这个建模很克制，但已经够用：

  • 分类有名称、描述、排序、公开状态、创建者
  • 链接有名称、URL、环境、描述、图标、排序、公开状态、所属分类、创建者

整个 schema 里还有几个值得注意的细节：

  • 用触发器自动维护 updated_at
  • 给公开数据和个人数据分别建了索引
  • 给 name 和 description 建了 pg_trgm GIN 索引
  • 通过 (created_by, name) 和 (created_by, category_id, name) 做唯一约束

这说明作者并不是只想把东西存进去，而是已经考虑到搜索、排序和多用户隔离这些真实使用问题。

3. 权限层 ​

这个项目最像"正式产品"的一点，在于它不是前端自己判断权限，而是把权限下沉到了数据库层。

Supabase schema 里启用了 RLS，并且分别定义了：

  • 匿名用户只能读公开分类和公开链接
  • 已登录用户可以读公开数据和自己的私有数据
  • 插入、更新、删除只能操作自己的数据
  • 链接写入时还会检查所属分类是不是当前用户自己的分类

这一层很关键。

因为很多小项目在早期最容易偷懒的地方，就是权限只做在页面上，数据库其实没有真正拦住。 但 NavSphere 这套写法，已经是比较稳的做法了。

4. 认证层 ​

认证采用的是：

Supabase Auth + GitHub OAuth

这套组合非常适合开发者工具项目。

原因也很简单：

  • 目标用户本来就有 GitHub 账号
  • 不需要自己维护密码体系
  • 登录链路短
  • 后续如果要和开发工具生态结合，也更自然

项目里当前只保留了 GitHub 登录方式，这其实是对的。

在这类小型项目里，过早支持邮箱、短信、多个 OAuth Provider，往往只会把复杂度抬高，但对早期价值没有明显帮助。

5. 运维辅助层 ​

这个项目还有一个很实用的小设计：Chrome 书签导入脚本。

仓库自带 scripts/export-chrome-bookmarks.mjs，可以把本地 Chrome 书签导出成项目可导入的 JSON 格式。

这件事看起来不大，但很有产品意识。

因为导航站最常见的问题不是"系统做不出来"，而是：

第一批数据怎么进来。

如果每个人都要手动录入几十上百个链接，系统的可用性会下降很多。 而书签导入脚本一加，迁移成本马上就低了一截。

这个项目的结构为什么适合 AI 协作 ​

NavSphere 很适合拿来说明一个问题：

不是所有项目都同样适合 AI 辅助开发。

它之所以适合，是因为它同时满足了几个条件：

  • 目录结构清晰
  • 模块职责分明
  • 技术栈主流
  • 依赖链不复杂
  • 数据模型简单但真实
  • 页面数量不多，但闭环完整

仓库的主结构大概是这样：

text
app/                    路由、页面、API、OAuth 回调
components/             前台和后台组件
lib/data/               导航查询、后台查询、导入逻辑
lib/supabase/           Supabase 客户端封装
data/                   导入示例数据
scripts/                Chrome 书签转换脚本
supabase/schema.sql     数据库结构与 RLS 策略

对 Codex 或 Claude Code 来说，这种项目有几个天然优势：

  • 很容易快速扫清全局上下文
  • 很容易定位修改点
  • 很容易做端到端的小闭环改动
  • 很容易把"页面、接口、数据库"串起来理解

换句话说，这不是那种需要先读三天历史包袱才能动手的项目。 AI 工具能直接进入高价值区。

它是怎么部署的 ​

从仓库信息看，NavSphere 当前的部署思路很明确：

前端部署在 Vercel，数据和认证放在 Supabase。

当前线上访问地址是：

这是现在做小型 Next.js 全栈项目非常顺手的一套组合。

1. Vercel 部署前端 ​

仓库里已经存在 .vercel/project.json，并且依赖中也接入了：

  • @vercel/analytics
  • @vercel/speed-insights

这基本说明项目已经按 Vercel 的方式在跑了，或者至少已经完成了绑定。

对 Next.js App Router 项目来说，Vercel 的好处非常直接：

  • 零配置支持 Next.js
  • Route Handler、SSR、静态资源都能自然托管
  • 预览部署方便
  • 和 GitHub 工作流贴合

2. Supabase 承担数据与登录 ​

部署这个项目时，真正需要先准备好的其实不是 Vercel，而是 Supabase。

最小步骤大概是：

  1. 新建一个 Supabase 项目
  2. 在 SQL Editor 执行 supabase/schema.sql
  3. 在 Auth 里启用 GitHub Provider
  4. 配置 GitHub OAuth 回调地址
  5. 准备环境变量

项目当前需要的关键环境变量非常少：

env
NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=...

也就是说，它的部署门槛其实不高。

3. 一条比较实际的上线链路 ​

如果我来部署这个项目，我会按这个顺序：

  1. 先把 Supabase 项目和 schema 跑起来
  2. 配 GitHub OAuth，确认本地登录回调正常
  3. 在本地导入一批样例数据
  4. 再把仓库接到 Vercel
  5. 在 Vercel 配同样的环境变量
  6. 把 GitHub OAuth 回调地址补上生产域名

这样做的原因是：

这个项目真正复杂的不是前端构建，而是"登录 + 数据权限 + 数据初始化"这三件事要一次打通。

前端页面本身反而是最好部署的部分。

用 Codex 和 Claude Code 做，这个项目到底有多快 ​

这部分是我觉得最值得聊的。

从 Git 提交记录看，NavSphere 的时间线非常集中：

  • 首个提交：2026-04-07 16:22
  • 最新提交：2026-04-08 13:06
  • 共 14 次提交

如果只看活跃提交窗口，这个项目的主开发期基本就集中在两段时间里：

  • 4 月 7 日傍晚
  • 4 月 8 日上午到中午

而从代码变化量看，在首个提交之后又累计发生了：

  • 56 个文件变更
  • 6397 行新增
  • 757 行删除

这个规模说明它不是单纯改个 landing page，而是实打实把一个小型全栈产品骨架补全了。

我的判断：这是一个典型的"0.5 到 1 人日 AI 项目" ​

如果把 Git 时间线、项目范围和实现复杂度放在一起看，我会这样判断：

在 Codex + Claude Code 的帮助下，这个项目做到当前程度，大概率属于 0.5 到 1 人日可以完成的范围。

这里说的不是"上线运营级产品全部完成"，而是：

  • 能跑
  • 能登
  • 能管
  • 能导
  • 能部署
  • 权限基本正确

这个版本已经具备了。

如果完全手写，时间大概率会拉长 ​

如果换成传统纯手工开发，我对这个项目的估算会更接近：

  • 经验熟练的全栈开发者：2 到 4 人日
  • 如果还要一边查文档一边搭：可能更久

因为它虽然不大，但有几类事情其实都挺花时间：

  • Next.js App Router 路由和页面组织
  • Supabase SSR 客户端封装
  • GitHub OAuth 回调接通
  • RLS 策略写对
  • 后台管理页和导入流程串通
  • 数据导入格式和校验逻辑统一
  • 本地验证 + 部署验证

这些事情单个看都不大，但凑在一起很容易把开发时间拉长。

而 AI 工具最擅长的，就是把这些"中等复杂、模式清晰、重复度高"的工作一段段吞掉。

Codex 和 Claude Code 各自适合干什么 ​

如果让我把这类项目拆成两种 AI 工具的优势，我会这样理解：

Codex 更适合：

  • 直接进仓库做结构化修改
  • 读现有代码后补齐缺口
  • 把页面、接口、数据层一起串起来改
  • 做验证、构建、查错、收尾

Claude Code 更适合：

  • 快速展开方案
  • 推导页面和模块结构
  • 起草一版较完整的实现
  • 做较长链路的代码生成和说明

当然，现实里它们往往不是二选一，而是接力关系：

Claude Code 更像高吞吐的第一轮实现，Codex 更像强执行和强收口的第二轮工程化推进。

这也是为什么现在很多项目做起来，速度会明显比过去快。

人工出力还剩多少 ​

这也是很多人最关心的问题。

我的答案是：

人工出力并没有消失，但已经从"大量敲代码"转移成了"做决策、给约束、验结果"。

如果以 NavSphere 这种项目为例，我会把人工出力大致理解成下面几个部分。

1. 人来定义边界 ​

比如这些事，仍然非常需要人来定：

  • 这个项目到底是公开导航站，还是带私有空间的导航站
  • 登录方式为什么只保留 GitHub
  • 分类是否支持路径式命名
  • 数据导入到底采用什么 JSON 结构
  • 后台要做到什么程度算够用

这些不是代码生成问题，而是产品决策问题。

2. 人来确认权限和安全 ​

AI 可以写出 RLS 策略，但最后最该负责的人还是开发者自己。

尤其是像这种涉及：

  • 匿名可读
  • 登录后可读私有数据
  • 用户只能写自己的分类和链接

这种边界，一定要人工做最终确认。

3. 人来做验收 ​

真正影响项目质量的，往往是这些最后一公里：

  • 登录回调是不是正常
  • 导入的数据有没有脏格式
  • 排序是不是符合预期
  • 空分类到底显不显示
  • 生产环境回调地址有没有漏配

这些检查 AI 能辅助，但很难完全替代人工判断。

4. 一个比较现实的占比判断 ​

如果只是问"代码体力劳动"的占比，我会觉得在这类项目里，AI 已经可以吃掉大约 60% 到 80%。

但如果问的是整个项目交付过程里的总出力，我的判断会更保守一点：

人工仍然要承担大约 20% 到 40% 的关键工作量。

这些工作主要不是敲代码，而是：

  • 需求取舍
  • 环境配置
  • 数据准备
  • 权限确认
  • 验收和收口

所以今天真正高效的开发方式，不是"AI 全做，人什么都不管"，而是：

人负责方向和边界，AI 负责高密度执行。

我觉得这个项目最有代表性的地方 ​

NavSphere 这个项目有代表性，不是因为它多复杂，而是因为它刚好落在一个很有现实意义的区间里：

  • 足够小，个人开发者能在短时间推进
  • 足够完整，不是只能截图展示
  • 足够真实，已经有权限、导入、后台、部署这些实际问题
  • 足够标准，AI 工具很容易介入

这类项目特别适合现在的 AI 编程工具。

因为它既不是过于简单的 demo，也不是充满历史包袱的大型遗留系统。 它属于那种：

AI 能真正把开发速度提升到肉眼可见程度的黄金区间。

最后 ​

如果只看结果，NavSphere 像是一个"普通的导航站项目"。

但如果把它放到开发流程里看，它其实更像一个信号：

现在做一个有登录、有数据库、有后台、有导入、有部署链路的小型全栈应用，真的已经进入了"周末可做完"的阶段。

前提不是 AI 会魔法，而是你要选对项目形态：

  • 技术栈主流
  • 结构清晰
  • 业务边界明确
  • 能快速验证

当这些条件满足时，Codex 和 Claude Code 这样的工具，确实能把项目推进速度提升到过去很难想象的程度。

而人最重要的价值，也会越来越集中在那几件事上：

  • 想清楚做什么
  • 判断什么是对的
  • 决定什么先做、什么不做
  • 把项目收口到可交付状态

这可能才是 AI 开发真正开始成熟的标志。

Last updated: