别再把架构靠嘴传了：我用 fcontext 让新同事的 AI 第一天就读懂项目
很多团队觉得，新同事 onboarding 慢，是因为项目太复杂、代码太多、业务太绕。
但这两个月我越来越确定，AI 编程时代里更大的问题其实不是这个。
真正拖慢 onboarding 的，是团队没有把项目状态持续沉淀下来。
结果就是：
- 新同事来了，要重新讲一遍架构
- 新开一个 AI 会话，要重新讲一遍项目
- 换一个 AI 工具，又要重新讲一遍边界和坑
表面上是在带新人，实际上是在重复做“项目认知迁移”。
我最近用 fcontext 跑通了一套更顺手的做法：
不是继续优化 prompt，而是把架构原则、需求边界、历史决策直接沉淀进项目，让新同事和他的 AI 一起继承。
这篇不聊概念，直接讲我怎么把这件事做成一套工程实践。
先说结论：onboarding 慢，很多时候不是人不行，而是项目状态没被交付出去
以前我也以为，新同事第一周效率低，是正常现象。
拉代码、配环境、跑项目、熟悉目录、看历史 PR、问老员工，这是传统流程。
问题是，现在大家都在用 Cursor、Copilot、Claude Code 这类 AI 工具。
所以 onboarding 已经不是单纯“教一个人”，而是同时在做两件事：
- 让新人理解项目
- 让新人的 AI 也理解项目
而第二件事，很多团队其实还没认真面对。
如果团队知识只存在于：
- 老员工脑子里
- 群聊记录里
- 一些没人维护的 wiki 里
- 几份 PDF 和 DOCX 文档里
那新人就算很努力，他的 AI 也只能从一堆零散信息里瞎猜。
这时候真正的问题不是“模型够不够强”，而是：
项目状态有没有被持续维护，能不能被新人和 AI 一起继承。
以前的 onboarding，为什么总像在重复做口述架构评审
你应该见过这种场景。
新同事第一天问你：
这个项目用户鉴权到底走哪一层？
你开始讲：
- 为什么这块不能直接改 Redis 缓存
- 为什么网关层要多一道兼容逻辑
- 为什么某个老接口虽然丑，但暂时不能删
- 为什么需求文档里那句话其实不能按字面理解
讲完之后，他转头去问 AI：
帮我给这个模块加个 Google 登录。
然后 AI 一本正经地给出一套看似很对、实际完全不符合现有架构的改法。
于是你又得再来一次。
这就是很多团队真正贵的地方：不是代码写慢，而是认知传递一直在重跑。
以前这个成本只是发生在人和人之间。
现在变成了：
- 老员工对新人讲一次
- 新人再对自己的 AI 讲一次
- 换个 AI，再讲一次
如果每个人的 AI 都是一座信息孤岛，团队规模越大，这个成本只会放大。
问题不在 prompt，而在项目状态没有被持续沉淀
很多人一看到 AI 理解错项目，第一反应是：
- 是不是 prompt 写得不够完整
- 是不是模型还不够强
- 是不是上下文窗口还不够大
这些当然有影响，但我现在更倾向于把问题定义成另一件事：
项目状态默认没有落成一套可继承、可维护、可复用的上下文系统。
这件事可以拆成几类断裂：
- 跨会话断裂：新会话一开，项目背景又要重讲
- 跨工具断裂：Copilot 里聊过的东西，Claude 不知道
- 跨成员断裂：每个人给 AI 喂的是不同版本的项目认知
- 跨文档断裂：PRD、方案文档、表格规范根本进不了 IDE 里的 AI
- 跨时间断裂：上个月踩过的坑，这个月又得重踩一次
如果问题定义在这里，那解决方向就不该只是“把 prompt 写得更长”，而应该是：
把项目知识变成一种可以随着仓库持续流动的资产。
fcontext 做的事情，不是让 AI 更聪明，而是让项目状态更容易继承
fcontext 的思路其实很朴素。
不是把记忆塞进某个单一模型里，而是把上下文结构化地落到项目目录里。
初始化之后，项目里会有一个 .fcontext/：
.fcontext/
_README.md # 项目摘要和关键原则
_workspace.map # 项目结构映射
_topics/ # 讨论沉淀下来的关键结论
_requirements/ # 需求、任务、演化关系
_cache/ # PDF / DOCX / XLSX 转成的 Markdown 缓存
你可以把它理解成一层给人和 AI 共用的“项目状态面板”。
对于 onboarding 来说，最关键的是这三类信息：
-
_README.md让 AI 先知道这个项目是干什么的、结构大致怎样、哪些原则不能碰。 -
_topics/让 AI 读到团队已经讨论过的坑、限制和历史决策。 -
_cache/让 AI 能看懂 PDF、DOCX、XLSX 里的产品和规格资料，而不是靠文件名瞎猜。
如果团队还有一套沉淀好的领域知识，还可以直接做成 experience pack，让新同事导入。
我现在更推荐的一套 onboarding 工作流
这套流程不复杂，核心是不要再把知识传递全靠人口述。
第一步：先把项目上下文落下来
老员工平时开发时，把关键背景和结论沉淀进 .fcontext/。
比如：
- 在
_README.md里补项目摘要和关键模块关系 - 在
_topics/里保留重要架构讨论和踩坑结论 - 在
_requirements/里把需求变更关系挂起来
第二步：把文档接进 AI 能读的格式
如果项目里有 PRD、设计稿说明、接口文档、Excel 规则表，先跑：
fcontext index docs/
这样这些二进制资料会被转成 Markdown，放进 .fcontext/_cache/。
以后新人和 AI 就能直接基于这些文档问问题，而不是靠你手工转述。
第三步：新同事接入时，不再从 0 开始
新同事拉完代码后，先接入 .fcontext/，再打开 AI IDE。
如果团队已经准备好了经验包，还可以直接导入：
fcontext experience import http://team-server/backend-domain.zip
或者从 Git 仓库同步：
fcontext experience import git@github.com:our-org/payment-domain-knowledge.git
第四步：先让 AI 读项目状态，再让它开始干活
这一步非常关键。
不是新人直接问：
帮我写一个 Google 登录。
而是先让 AI 在当前项目上下文里理解：
- 现在的鉴权链路是什么
- 哪些模块不能随便动
- 需求文档里有哪些边界条件
- 团队之前为什么做过某些取舍
这时候，AI 不再是一个刚进门的陌生人，而更像一个已经读过项目背景材料的新同事。
一张表看 before / after
| 场景 | 以前的做法 | 现在的做法 |
|---|---|---|
| 新人了解项目结构 | 找老员工口头讲 | 先读 .fcontext/_README.md 和 _workspace.map |
| 新人了解历史坑 | 翻群聊、问人 | 直接看 _topics/ 里的结论沉淀 |
| AI 理解需求边界 | 人工转述 PDF / DOCX | fcontext index 后直接读取 _cache/ |
| 团队共享知识 | 各自记各自的 | .fcontext/ 随仓库维护，或导入 experience pack |
| 首个 PR 的稳定性 | 很依赖带教质量 | 更依赖项目状态是否被沉淀完整 |
对我来说，最大的变化不是“新人突然变天才了”，而是：
团队终于不需要每来一个人，就重新发明一次项目认知。
用一张图看这件事为什么成立
flowchart LR
A[老员工的架构经验]
B[需求文档和规格资料]
C[历史讨论与踩坑结论]
A --> D[.fcontext]
B --> D
C --> D
D --> E[新同事]
D --> F[新同事的 AI]
E --> G[更快理解项目]
F --> H[更稳定的首个交付]
这里最关键的一点是：
团队传递的不再只是代码，而是项目状态本身。
这套方法的边界也要说清楚
为了避免文章写得像广告，这里把边界直接讲明白。
1. 它不能替代架构设计
fcontext 不能帮你做正确架构，它只能帮你把已经形成的架构认知持续交付出去。
2. 它不能保证 AI 永远正确
如果上下文本身过期、错误、矛盾，再好的模型也会在错误地面上推理。
3. 如果团队不维护上下文，这套东西也会失效
这类工具的前提不是“装一下就完了”，而是团队愿意把关键知识顺手沉淀下来。
4. 更适合有重复解释成本的团队场景
如果你只是单人写 demo，这套方法感知不会特别强。
但如果你有这些场景，它会明显更有价值：
- 新人 onboarding 频繁
- 多人一起用 AI 编程
- 需求和架构经常演进
- 项目里有大量 PDF / DOCX / Excel 文档
最后一句话总结
很多团队 onboarding 慢，不是因为新人学得慢，也不是因为 AI 不够聪明。
而是因为项目状态没有被当成一项可以持续维护、持续继承、持续交付的资产。
fcontext 对我最有价值的地方，不是让 AI 一次读更多，而是让新人和他的 AI 站在同一块地面上开始工作。
如果你们团队现在最痛的事情，也是每来一个人就得重新讲一遍架构、重新解释一遍需求、重新让 AI 熟悉一遍项目，那这类做法值得你认真试一次。
GitHub：github.com/lijma/agent-skill-fcontext
你们团队现在 onboarding 最耗时间的，是代码结构、需求背景，还是历史决策？
