一个普通前端的 Claude Code 实战手记

起因是一个朋友,和一张被划得乱七八糟的角色卡

去年冬天有次跑团,新来的朋友小张,坐我旁边建角色。一个法师,从八点建到快九点,角色卡被铅笔划了又擦、擦了又划,擦出毛边,最后能力值那栏还填错了——他把调整值当成了属性值填进去,导致整张卡的数据全错位。等我发现的时候,这局已经开打半小时了。

那天回家路上我就在想,这事儿也太离谱了。

玩过 DND(龙与地下城)的人大概都熟悉那个画面。你坐在桌边,面前一张空白角色卡,规则书翻到第三章,旁边的老玩家随口一句:“先选种族,再选职业,能力值用 4d6 去掉最低骰。”你点点头,装作听懂了,然后开始在十几张表格之间反复横跳,想搞明白精灵的黑暗视觉到底是 60 尺还是 120 尺,战士 1 级给几个专长,力量 14 对应的调整值是 +2 还是 +3。

DND 2024 新版规则改了不少,光规则书的厚度就够把新人挡门外。我自己带过的新人没有十个也有八个,每次都得搭进去半小时帮他建角色。倒不是规则有多难,而是信息太散。建一个角色要在种族、职业、背景、装备表之间来回查七八处,每一处都可能填错,错了还会连锁影响后面所有计算。

更要命的是,这些错误新人自己根本发现不了。他不知道矮人有“中毒豁免优势”,所以他根本不会去找这一条;他不知道力量影响的是近战命中而不是法术,所以他算错了也察觉不到。规则的复杂度,全压在了一个对规则最不熟的人身上。

那阵子我心里一直有个念头,觉得这事本该有个软件来替你做。市面上不是没有在线建角工具,但要么全是英文,新人光看界面就退缩;要么功能堆得满满当当,把进阶玩家才用得上的东西一股脑全摆出来,反而把“我就想快点建个一级角色”这个最朴素的需求淹没了。我想要的特别简单:一个专门服务 DND 2024 中文版的东西,一步一步牵着新人走,每一步只让他做一个决定,数据全自动算好,手机上也能用。

问题是,这事我做得了吗?

说实话,我没什么底气

我是个普通前端,工作几年,Vue 写得还算熟,平时就是做做业务页面。但我不是设计师,也没自己从头到尾做出过一个完整的产品,所谓“软件”这个东西,我从没独立做成过。

我清楚自己几斤几两。功能让我写,我能写出来,但界面我是真不行,自己配色能配出一股土味;逻辑我能理顺,可那些边边角角的情况我老是想不全,经常是上线了才被人发现漏了个分支;组件怎么拆我门儿清,但要我说清楚整个项目的数据该怎么组织、各个模块之间怎么串,我就含糊了。说白了,我习惯的是在别人搭好的框架里填空,真给我一张白纸让我从头规划一个完整的东西,我心里没底。

这种没底是有代价的。我电脑里躺着好几个做了一半的项目,都是兴冲冲开了头,做到某个卡点过不去,或者越做越乱、自己都嫌弃,然后就放那儿吃灰了。所以这次开工之前,我对“能不能做完”其实没抱太大期望。

唯一跟以前不一样的,是这回我用上了 Claude Code。

它是 Anthropic 出的一个 AI 编程工具。跟大家熟悉的那种聊天 AI 不太一样:聊天 AI 你得把代码一段段复制给它、它再回一段给你,中间隔着一层。Claude Code 是直接在你电脑上跑的,它能打开你这个项目里所有的文件,自己读、自己改,就像你请了个工程师坐到你电脑前,而不是隔着微信远程指挥一个看不见你屏幕的人。这个区别后面会越来越明显——很多事之所以能成,正是因为它“看得见全貌”。

但工具是工具,怎么用是另一回事。我一开始也踩过坑:什么都不想,直接把活儿整个甩给它,让它自己看着办。结果它确实能给你跑起来的东西,可点开代码一看,各种情况没考虑周全,这个分支没处理、那个边界没兜住;代码也冗余得厉害,同样的逻辑换三个地方各写了一遍,改一处得满项目找。表面上看是它写的,实际上是没人在掌舵,它只能顺着字面意思一路猜下去,越猜越偏。

所以这两周我慢慢摸出来的,与其说是“怎么让 AI 写代码”,不如说是“怎么用好它”。下面这几步,基本就是我踩着坑总结出来的。

第一步:把事情讲明白,而不是丢一句命令

很多人用 AI 写代码是这样的:“帮我写一个角色创建页面。”然后收获一坨通用的、跟自己项目八竿子打不着的代码,改起来比自己重写还累。我一开始也这么干过,吃过亏。

所以这次我做的第一件事不是让它写代码,而是跟它讲业务。

我花了大概二十分钟,把 DND 2024 的建角流程从头到尾给它讲了一遍。流程是线性的,分十步:选种族、选职业、选背景、分配能力值、选专长、选法术、选装备、定生命值,最后生成角色卡。关键是每一步之间都有数据依赖。职业决定你能穿什么甲、用什么武器;种族决定你有没有黑暗视觉、有没有特定豁免优势;背景给你额外的技能熟练。这些东西在建角过程中是分散选的,但最后必须全部正确地汇总到一张角色卡上。

讲完之后我没说“帮我写代码”,我说的是:“我需要一个响应式状态对象来存角色数据,涵盖种族、职业、背景、能力值、专长、法术和装备。每个字段该存什么,你帮我把数据结构设计出来。”

讲需求,而不是直接要代码:让它先帮我设计数据结构

它返回了一份完整的character状态设计,字段分门别类,连“这个字段为什么要这么存”都给我标了注释。我扫了一眼,挑出一个问题:法术这块不够,法师和牧师的法术来源不一样,一个靠智力一个靠感知,得支持多来源。它立刻调整。来回三四轮,整个项目的数据骨架就定下来了。

那一刻我有个很微妙的感受。这个数据结构,要我自己从零设计,我得反复推翻好几次,搞不好做到第八步才发现第一步的结构不够用,然后回炉重来。但因为我把业务讲透了,它在一开始就帮我把坑给绕过去了。

值得说一下的是,这种讨论之所以管用,是因为它能记住我们已经定好的所有东西。它不是这一句回答完就忘,而是把整个项目的设计都揣在脑子里。这意味着后面我每加一个新功能,它都知道该跟前面已有的部分对上,而不是另起炉灶。这是和 AI 协作里最该先做的一件事:你得先把业务讲清楚,让它明白你到底在做什么,而不是张口就要代码。你对业务理解得越深,它给你的东西就越准。

第二步:风格是聊出来的,不是调出来的

我想要个什么样的界面?脑子里只有个模糊的感觉:暗黑系,有奇幻感,带点羊皮纸和古卷的气质,但又得现代、耐看,手机上也能用。

我不会设计,也调不来配色。让我自己挑颜色,我大概率会调出一套土味十足的东西。但我会用语言描述。

我跟它说,整体走深色背景,主色用旧金色和暗铜色,底色接近墨黑,要有羊皮纸的质感但别真贴纹理图,用渐变和阴影去做层次;字体要有奇幻味,标题用装饰性字体,正文保证可读。

第一版出来,我把页面跑起来的瞬间,说实话有点小激动——它真的有那个味儿了。但细看还是不行,我说金色太亮,显廉价,降一档,边框换成更细、半透明的。它改。我又说种族选择页那些卡片悬浮效果太平,加点发光。它再改。我说过了,发光太冲,像游戏 UI,克制点。

来回纠了三五轮后稳定下来的种族选择页

就这么来回纠,一个页面通常改三到五轮,风格也就稳了。整个过程特别像在跟一个手很快、但需要你不断给方向的设计师合作。我负责说“这里不对”,它负责立刻给我看下一版,这种即时反馈的爽感,是我以前自己一个人对着 CSS 死磕时从来没有过的。

风格定下来之后,我交代它一句:之后所有页面都按这个风格来,每次写新页面前先去读已经做好的那几页。

我每开一个新功能,都先甩一句“参考 RaceSelect 的风格和代码结构”。注意,这不是一句空话——它真的会去把那个页面的文件从头读一遍,看我之前是怎么配色、怎么排版、代码怎么组织的,然后照着这套来写新页面。换成普通聊天 AI,你就得手动把那个页面的代码全复制过去喂给它,既麻烦又容易漏。而它能自己翻文件,这件事就变得几乎不费力。最后做出来八个页面放在一起,像是一个人一口气写完的,靠的就是这个。

第三步:遇到 bug,让它去找证据,别让它瞎猜

做到一半,我撞上一个问题。选了矮人之后,角色卡上既没显示“矮人刚毅”的每级 +1 HP,也没显示“中毒豁免具有优势”这条特性。

这恰恰就是我最初想解决的那类错误。一个新人根本不会发现自己漏了这两条,而我的软件本该替他记住——结果我自己的软件先漏了,有点讽刺。

第一反应当然是“AI 写错了”。但我没直接甩一句“你写错了,改一下”。这么说的话,它大概率会随手乱改一通,问题没解决,还可能给你引出新的坑。我以前就这么被坑过,改一个 bug 冒出来俩。

我换了个路子,先让它帮我找证据,确认问题出在哪一层,再动手。我说,矮人角色卡上没显示豁免优势,我不确定是数据本身就没这个字段,还是数据有、只是没被显示出来;你先去查种族数据文件里矮人的数据,看这字段在不在,再看角色卡模板里有没有读这个字段。

它查完告诉我,种族数据里 savingThrowAdvantages这个字段是完整的,矮人的数据没问题,但角色卡模板里压根没渲染过它。同样的毛病,HP 计算函数也根本没接收种族加值这个参数。

所以病根不在数据,在展示层漏了。根因一锁定,修复就花了几分钟。

这里其实藏着它一个很顶用的本事:这个 bug 牵扯到三个不同的文件——存数据的、显示角色卡的、算 HP 的。它能同时把这三个文件都打开,顺着我的角色卡一路倒查回数据源,最后定位到中间的显示环节漏了。这种跨好几个文件、顺藤摸瓜的活儿,要是靠我自己一个文件一个文件地翻,又慢又容易看花眼。

这是整个开发里我体会最深的一点。碰上 bug,先定位再动手,别让 AI 去猜,要让它拿证据。像“我感觉是哪哪的问题,你帮我改改”这种说法,成功率到不了一半;换成“先查数据层有没有这字段,再查显示层有没有读取”,基本是一次定位、一次修复。这个习惯后来救了我很多次,也省下了大把来回扯皮的时间。

第四步:它卡死的时候,换个角度逼它

法术书翻页是整个项目里最磨人的一段,没有之一。

DND 法师有一本法术书,我特别想做成真能翻页的那种效果,每页都有法术内容,翻动时带点纸张的物理手感。这其实是个有点“虚荣”的功能,对建角本身没那么必要,但我就是想要,觉得有了它整个法师体验才完整。为此引入了一个叫 StPageFlip的库。

结果 Claude 前后改了六回,每次都拍胸脯说这下应该行了,可一跑要么翻不动、卡在第一页,要么直接白屏崩掉。改到第五回的时候我是真有点上头了,差点就想把这功能砍掉算了。

但我忍住了,换了个方式。没再说“还是不行,再改”,而是这么讲的:停,先别动代码,我们得先搞清楚这个库初始化到底需要满足什么条件;你去读它的文档,告诉我它要求 DOM 节点在什么时机必须存在,再对照我们现在的代码,指出问题卡在哪。

不让它继续改,而是让它先去读库的文档、把根因讲清楚

这一回它揪出了真正的元凶。StPageFlip要求初始化时 DOM 必须已经渲染完成,而我们是在 onMounted里直接初始化的,那会儿 Vue 还没把页面内容塞进 DOM,翻页插件抓了个空。这里又用上了它一个很省事的能力:StPageFlip是别人写好的现成工具,我对它的内部规矩一无所知,但它能直接把这个库自带的说明文档和源码翻出来读,把那条藏起来的要求挖出来,再回头对照我们的代码一眼看出问题。这事换我自己来,得在网上搜半天、试半天。根因一确认,把初始化挪到 nextTick之后,两分钟搞定,从此再没犯过。

修好之后真正能顺滑翻起来的法术书

那本法术书第一次顺滑翻起来的时候,我盯着屏幕翻来翻去翻了好几遍,纯粹是因为好玩。前面五次的窝火,在那一下全值了。

我的经验是,当 AI 来回改都解决不掉同一个问题时,别让它继续改,该喊停了,切到先分析、再动手的模式。反复改三次以上还搞不定的 bug,几乎都是因为根因压根没找到,在错误的方向上改得再勤也是白费。

第五步:把你不擅长的活交给它

软件做得差不多,我发给跑团群里几个朋友试。一个常当 DM(地下城主)的哥们儿用完提了个需求:“挺好的,但我跑的是自定义设定,有几个自创种族,你这里能加吗?”

这需求很合理,但对我是个不小的工程量。它意味着要做一个后台管理页,增删改查、表单校验、图片上传、数据持久化全得有。前面那些建角页面我好歹熟,这种带完整后台的东西,要我自己从头做,起码搭进去一周,而且大概率做得很糙。

我跟 Claude 说,我要一个 DM 管理页,能在不改代码的前提下新增种族、职业、背景,数据格式得跟现有的 hardcoded 数据完全一致,这样玩家的建角流程一行代码都不用动,就能直接用上新加的内容。

它反问了我几句:数据存哪,本地还是服务器?图片怎么处理?要不要权限控制?这几个问题问得挺到位,有两个是我压根没想到的。

我一一答了,它给出方案:Node.js 起一个本地服务,数据用 JSON 文件存,前端管理页直接调接口,新增的数据格式和原有 hardcoded 数据严格对齐,所以建角那边一个字都不用改。我说行,再补上对 UI 的要求,它就开写了。值得一提的是,它不只是把代码写出来——装依赖、起本地服务、跑起来验证,这些命令它能自己在终端里敲,我基本只需要看着结果说“行”或者“这里不对”。

整个管理功能,从我提需求到第一版跑通,不到两小时。我那哥们儿当晚就把他的自创种族录进去了,然后用我的软件建了个角色,截图发群里。那一刻挺奇妙的——我做的东西,真的在解决另一个人的真实问题了,而这速度,我一个人无论如何也达不到。

让它横跨数据层和展示层去查证据,而不是凭感觉乱改

两周之后,我手里多了什么

22 次提交,从零到一款能用的 DND 建角软件。

它现在能做到:引导新人走完完整的十步建角流程,每一步只需要做一个决定;中文化了 DND 2024 全部核心种族、职业、背景数据,新人不用再啃英文规则书;能力值调整值、AC、HP、熟练加值全自动算好,从根上杜绝了小张那种填错位的事;法师有专属法术书界面,可以翻页查阅已知法术;DM 能通过管理页自行新增种族、职业、背景,不用改一行代码;最终生成一张完整角色卡,截图就能保存,直接发给 DM。

不够好的地方也有:数据覆盖还不全,目前只到核心手册,扩展模组里的东西还没补;没有账号系统,数据存在本地,换台设备就得重来;移动端适配还有些细节没打磨。

但对一个两周的个人项目来说,这早超出我原本的预期了。

这件事真正教会我的

不是“AI 能帮你写代码”,这谁都知道。

我后来想明白的是,你对一件事懂得越深,AI 能帮你做的就越多。我懂 DND 的规则,所以我说得清数据结构要存什么、边界在哪、哪段逻辑不合规、矮人那条豁免优势该挂在哪一层。这些判断没有一个是 AI 替我做的,它做的只是把我的判断翻译成代码,而且比我自己写快得多。反过来,一个对 DND 一无所知的人,直接丢给 AI 一句“做个 DND 建角软件”,它会还你一堆看着像样、一推就倒的东西。能跑,但规则全是错的,他自己还看不出错在哪。

但让我感触最深的,其实是另一层。

你想想,DND 建角这个需求,真实存在,而且不止我一个人需要。可它为什么一直没有一个好用的中文工具?不是技术上做不出来,而是这事太“小”了——它的用户盘子撑不起一个团队专门去开发。真正精通前后端、什么都能写的工程师,要么在做更大的项目,要么也犯不上为这么个小众需求花一周时间。于是这类需求就一直悬在那儿,谁都看得见,谁都不去做。

而最想做、也最知道该怎么做对的人,往往恰恰是被卡在代码这一关的那群人。一个跑了十年团的资深 DM,他比任何工程师都清楚这软件该长什么样、哪条规则不能错,但他可能连 Vue 是什么都不知道,这道门槛就把他挡在了外面。

vibe coding 真正动人的地方,就在这儿。它没有把工程师替换掉,它是把那群“懂行,但苦于代码略弱”的人,头一回放进了开发这件事里。你深耕的那个领域、你脑子里那些别人没有的判断,以前因为不会写代码,只能停留在“要是有个软件就好了”的念想里;现在它们能落地了。我这两周做的,本质上就是把我对 DND 的理解,借着 AI,变成了一个真的能用的东西。

我以前总觉得做一个完整的“软件”是另一个量级的事,是属于“产品团队”的事,不是我一个写业务页面的前端能碰的。这两周改变了我这个看法。门槛没有消失,但它挪了位置——从“你得把代码写得多好”,变成了“你得真的懂你要解决的那件事,并且对它足够较真”。

写给想试试的人

Claude Code 目前需要订阅 Claude Pro,或者按 API 用量付费,在终端里运行,Mac 和 Windows 都支持。如果你用 VS Code,有配套插件,体验会更好。

门槛不算高,会用终端,有一点点编程基础就行。不必是全栈,甚至不必太懂后端,能看懂代码，会查资料去分析，且有创意这就足够了。

剩下你真正需要的,其实是对某件事有点执念。

我就是想让小张们建角时别再把卡划得乱七八糟,正是这点执念撑着我熬过了翻页崩溃的第五次、撑着我走完了两周,也让我清楚每个功能做到什么程度才算“对”。这份判断力 AI 给不了你,但有了它,AI 能陪你走挺远——远到你自己都有点吃惊。

附:Claude Code 怎么装、怎么上手

说点实在的,给真想动手试的人。下面这些信息会随官方更新而变,以 Anthropic 官方文档为准,这里只给个大概的路子。

先说账号。Claude Code 这个工具本身免费,但要用得有个付费账号撑着,可以是 Claude Pro(每月 20 美元,已包含 Claude Code 额度)、Claude Max,或者 Anthropic Console 的 API 充值(按 token 用量计费)。免费的 Claude.ai 账号用不了。一般个人开发,Pro 订阅就够折腾很久了。

再说环境。它跑在终端里,macOS、Linux 都能直接用;Windows 目前要走 WSL(也就是在 Windows 里开一个 Linux 子系统),不能裸装在原生 Windows 上,这点要注意。机器配置不挑,4G 内存起步就行,因为所有计算都在 Anthropic 的服务器上跑,你本地只是个发请求的客户端,但得联网。

装的方式有两种。官方现在推荐的是原生安装器,一条命令、不用先装 Node.js,还能后台自动更新:

# macOS / Linux,一行装好(具体命令以官网为准)curl -fsSL https://claude.ai/install.sh | bash

如果你本来就吃 Node 这套,或者想锁定某个版本,也可以走 npm(需要 Node.js 18 以上):

npm install -g @anthropic-ai/claude-code

装完别用 sudo 去装全局包,容易留下一堆权限的坑;真遇到权限报错,正经做法是改用 nvm 把 Node 装进自己的用户目录。

装好之后,在你的项目目录里敲一句 claude就进去了,第一次会让你登录(浏览器里用 Anthropic 账号授权一下)。然后你就可以像我前面那样,直接跟它讲你要做什么。如果你平时在 VS Code 里写代码,装个配套插件,体验会顺手不少。

剩下的就是前面整篇讲的那些事了:先讲清业务再要代码、让它对齐已有风格、遇到 bug 让它先查证据、卡住了就喊停换分析模式。工具就这么点,真正决定上限的,还是你对自己要做的那件事懂得有多深。

项目地址

项目还在迭代,核心建角流程已经能用,支持 DND 2024 中文规则,DM 可以通过管理页自定义内容。如果你是 DND 玩家,欢迎试用,也欢迎告诉我哪里还不够好。

在线体验:http://47.120.19.14:8088

源码(github):https://github.com/zaz-nlu/DND-create/tree/master