danci 项目（三）：从 JSON 数据到 AI Coding，真实项目里的数据清洗、Prompt 和工程规范

摘要：围绕真实项目中的数据导入与 AI 辅助开发展开，理解数据清洗、scripts、上下文管理、AGENTS.md、Prompt 颗粒度、Git 与 Conventional Commits 应该如何协同工作。

一、几千个单词不可能手工录入

一个单词学习系统可能需要：

text 复制代码

四级词汇
六级词汇
考研词汇
雅思词汇
托福词汇

这些数据加起来可能有几千甚至上万个单词。

如果后台管理员一个个录入，显然不现实。

因此更合理的方法是寻找已有的开放数据源。

例如：

text 复制代码

GitHub 开源单词仓库
↓
下载 ZIP
↓
获得 JSON 文件

这时候任务从人工录入单词变成：

text 复制代码

外部 JSON
↓
自己的 words 表

二、为什么拿到 JSON 后不能直接导入

外部数据是按照别人项目的需求设计的，而自己的数据库是按照当前项目的需求设计的。

两边的数据结构很可能不同。

例如原始数据：

json 复制代码

{
  "word": "apple",
  "trans": ["苹果", "苹果公司"],
  "phonetic": "...",
  "extra": "..."
}

而自己的 words 表可能只需要：

text 复制代码

word
meaning
phonetic

除此之外，还可能存在：

text 复制代码

重复数据
空字段
字段格式不统一
异常字符
错误数据
无用字段

因此导入之前通常需要数据清洗。

三、什么叫数据清洗

数据清洗不只是：

text 复制代码

JSON 转 CSV

格式转换只是其中一步。

真正的数据清洗可能包括：

text 复制代码

选择字段
删除无用字段
字段重命名
格式统一
去除重复
处理缺失值
过滤异常数据
数据校验
人工审核

完整流程可能是：

text 复制代码

原始数据
↓
分析结构
↓
选择需要字段
↓
格式统一
↓
过滤异常
↓
去重
↓
校验
↓
人工抽查
↓
导入数据库

四、为什么数据清洗是后端常见工作

真实后端项目并不只有写接口和 CRUD。

实际开发中经常需要处理：

text 复制代码

CSV
Excel
JSON
第三方 API
旧数据库
日志
爬虫数据
批量导入
数据迁移

这些数据几乎不可能天然符合当前系统的数据结构。

因此数据转换、数据清洗、批量处理和数据迁移，本身就是非常常见的工程任务。

五、为什么不应该把整个大 JSON 直接发给 AI

假设有一个很大的：

text 复制代码

words.json

最直接的方法可能是：

text 复制代码

把完整 JSON 发给 AI
↓
让 AI 帮忙转换成 CSV

技术上并非完全不可行，但从工程角度通常不够理想。

原因包括：

text 复制代码

大量原始数据占用上下文
token 开销增加
上下文窗口有限
转换过程难以重复
规则一改就可能重新处理
结果难以自动验证

更关键的问题是：

AI 真正需要理解的往往不是全部数据，而是数据格式和转换规则。

六、更好的方式：让 AI 写脚本

更合理的方式是只给 AI：

text 复制代码

输入格式
输出格式
字段映射
清洗规则

例如输入样例：

json 复制代码

{
  "word": "apple",
  "trans": ["苹果"]
}

目标：

csv 复制代码

word,meaning
apple,苹果

然后让 AI 编写：

text 复制代码

scripts/convert-words.ts

脚本负责：

text 复制代码

读取完整 JSON
↓
遍历数据
↓
转换字段
↓
清洗数据
↓
输出 CSV

于是变成：

text 复制代码

AI 写程序
↓
本地程序处理 10000 条数据

而不是：

text 复制代码

AI 在上下文中逐条处理 10000 条数据

这是一种非常重要的 AI Coding 思维：

当任务是大量、重复、确定性的计算时，优先让 AI 写程序，再让程序完成工作。

七、scripts 目录是干什么的

项目中经常会看到：

text 复制代码

scripts/

它通常用于存放：

text 复制代码

数据格式转换
数据导入
初始化数据
爬虫
批量修复
一次性任务
迁移辅助

例如：

text 复制代码

scripts/
├── convert-words.ts
├── import-words.ts
└── check-duplicate-words.ts

这些脚本通常不属于用户请求触发的线上业务接口。

它们更像为开发、数据处理和运维过程服务的小程序。

八、为什么脚本比直接让 AI 处理更好

1. 可重复

脚本可以反复执行。

2. 可修改

如果目标字段发生变化，只需要修改脚本。

3. 可测试

可以先拿少量样本验证，确认正确后再处理全部数据。

4. 可审查

脚本可以通过 Git diff 和 Code Review 检查逻辑。

5. 减少上下文浪费

AI 只需要理解格式、规则和目标，不需要读取全部原始数据。

九、AI Coding 最核心的问题之一是上下文

假设直接对 Coding Agent 说：

text 复制代码

帮我把单词书管理做完。

它马上会遇到很多未知信息：

text 复制代码

使用什么框架？
数据库是什么？
books 有哪些字段？
ORM 是什么？
UI 用什么组件？
删除逻辑是什么？
管理员权限是什么？
页面路由是什么？

如果这些信息没有提供，AI 只能猜。

而业务开发中最危险的情况之一，就是：

业务规则没有说清楚，但模型自行补全了一套"看起来合理"的实现。

十、Prompt 为什么要有合适的颗粒度

过粗的 Prompt：

text 复制代码

实现 books 管理

很容易产生歧义。

更清晰的任务可以写成：

text 复制代码

实现 /books 单词书管理页面。

技术要求：
- Next.js
- TypeScript
- Drizzle ORM
- shadcn/ui
- Tailwind CSS

books 字段：
- id
- name
- description

功能：
- 查询
- 创建
- 编辑
- 删除

业务规则：
- name 必填
- 删除前二次确认
- 使用现有数据库 schema
- 不修改无关页面

这类 Prompt 明确回答了：

text 复制代码

做什么
在哪里做
使用什么技术
数据是什么
业务规则是什么
哪些地方不要修改

Prompt 的目标不是"越长越好"，而是：

对当前任务来说足够准确、足够完整。

十一、上下文也不是越多越好

另一种极端是：

text 复制代码

每做一个小功能
↓
把整个项目全部塞给 AI

这同样不合理。

因为无关信息会增加模型处理成本，也可能干扰判断。

更好的原则是：

text 复制代码

上下文要充分
+
上下文要相关

十二、长期上下文和当前任务应该分开

有些信息长期不会频繁变化，例如：

text 复制代码

Next.js
TypeScript
shadcn/ui
Tailwind CSS
Drizzle
Supabase
目录规范
代码风格
数据库规则
Git 规范
禁止事项

这些更适合放在项目级说明中，例如：

text 复制代码

AGENTS.md

而当前 Prompt 只负责描述：

text 复制代码

这一次具体要做什么

于是形成：

text 复制代码

AGENTS.md
↓
长期项目规则

当前 Prompt
↓
当前任务

十三、为什么 schema 也是 AI 的重要上下文

假设 Supabase 已经存在 books 表，但 Coding Agent 不知道。

一种办法是每次在 Prompt 中描述：

text 复制代码

books 有 id、name、description...

更工程化的方式是让项目中存在：

text 复制代码

db/schema.ts

例如：

ts 复制代码

export const books = pgTable(...)

这使数据库结构本身成为代码的一部分。

于是：

text 复制代码

数据库结构
↓
schema.ts
↓
开发者和 AI 都能读取

这说明一个很重要的原则：

最好的上下文不一定全部写在 Prompt 里，很多上下文本来就应该存在于代码和项目文档中。

十四、如何理解"隐藏的上下文开销"

如果 Coding Agent 为了完成一个小任务读取：

text 复制代码

20 个无关文件
一个 200KB JSON
很多历史文档

这些内容都会增加模型需要处理的信息量。

因此更好的策略不是永远禁止 AI 读文件，而是：

尽量让它读取与当前任务真正相关的内容。

例如处理大型 JSON 时：

text 复制代码

不要读取全部 JSON
↓
提供结构样例
↓
明确目标格式
↓
让 AI 写脚本

这比单纯追求"上下文越多越好"更合理。

十五、为什么 Git 在 AI Coding 时代更重要

AI 可以一次修改大量代码。

一个功能可能同时修改：

text 复制代码

schema
页面
组件
接口
配置
测试

如果没有 Git，很难知道：

text 复制代码

这一次到底改了什么？
哪部分是新增的？
哪部分是误改的？
出问题以后怎么恢复？

使用 Git 后，可以通过：

text 复制代码

git diff

检查改动。

所以 Coding Agent 越能一次性修改大量代码，就越需要版本控制、diff、Review 和测试。

十六、Conventional Commits 是什么

项目可以使用：

text 复制代码

Conventional Commits
约定式提交

常见类型：

text 复制代码

feat      新增功能
fix       修复 Bug
docs      文档修改
refactor  代码重构
style     样式或格式调整
test      测试相关
chore     工具、构建、配置等

例如：

text 复制代码

feat: add books management

表示新增单词书管理功能。

text 复制代码

fix: prevent duplicate book names

表示修复单词书名称重复的问题。

它的重点并不是背这些英文单词，而是：

让 Git 历史更加清晰、统一和容易理解。

十七、把真实项目开发流程串起来

数据处理流程：

text 复制代码

GitHub 获取原始单词数据
↓
分析数据结构
↓
确定 words 表字段
↓
让 AI 编写清洗脚本
↓
本地执行
↓
检查结果
↓
导入 Supabase

功能开发流程：

text 复制代码

AGENTS.md
↓
提供长期项目规则

schema.ts
↓
提供数据库结构

Prompt
↓
描述当前具体任务

Coding Agent
↓
实现功能

Git diff
↓
人工检查

测试
↓
确认行为

Conventional Commit
↓
提交代码

这已经不再只是"让 AI 帮忙写代码"，而是一套：

text 复制代码

人
+
AI
+
代码
+
数据
+
规则
+
Git

协同工作的工程流程。

十八、真正值得掌握的几个判断

大量重复数据

不要优先考虑让 LLM 自己逐条处理，更好的方式是：

text 复制代码

让 AI 写脚本
↓
让程序批量处理

AI 不知道业务规则

不要让模型猜。

应该提供：

text 复制代码

技术架构
数据结构
业务规则
功能要求
约束
验收标准

长期规则

不要在每个 Prompt 中重复。

更适合放在：

text 复制代码

AGENTS.md
项目文档
代码结构
schema

AI 修改了大量代码

不要直接相信结果。

应该：

text 复制代码

Git diff
↓
Review
↓
测试
↓
提交

十九、整个 danci 项目的三条主线

最终，整个项目可以浓缩成三条主线。

第一条：

text 复制代码

业务需求
↓
后台 + H5
↓
Next.js + shadcn/ui

第二条：

text 复制代码

业务数据
↓
Supabase PostgreSQL
↓
Drizzle ORM
↓
schema / relation / RLS

第三条：

text 复制代码

真实数据 + AI Coding
↓
scripts
↓
清晰上下文
↓
AGENTS.md
↓
Git

把这三条线串起来以后，项目中的技术就不再是一堆孤立名词。

它们共同构成了一条完整的开发路径：

从需求设计，到数据库建模，再到真实数据处理和 AI 辅助开发。