天猫新品以分层知识库和Skills建设Spec体系

MDI 是一个横跨 4 个角色端、约 40 个功能模块的全栈 AI 平台项目，启动时只有一两个人，最大痛点是 AI 不知道项目是什么。团队在根目录放一份 AGENTS.md 作为 Agent 进入项目的唯一入口，明确“本文件是 Agent 的入口地图（≤120 行）。不放细节，只告诉你去哪里找”，用仓库地图（覆盖 workspace-mdi/ 下 7 个子仓库及端口、开发入口、废弃仓）、快速命令、关键约定速查表（时间字段、日志体系 BizLog/@BLog、MTOP 路由 @MtopController 等踩坑强约定）、当前状态表四个板块串起多仓库聚合工作区；AGENTS.md 行数由 collar-runbook Skill 守卫，逼近 115 行即提醒把详情迁到 docs/。知识落点为 docs/ 下 specs（业务地图，16+6+14+1+2 个功能模块）、changelog、architecture、runbook、vendor、wiki 六个模块，每个模块配唯一 Skill构成模块-骨架-README 三位一体，六个 Skill 的触发方式分主动/被动两档。关键机制是把 git commit 设计成统一触发关卡：一次提交同时驱动 collar-changelog 记录变更、collar-runbook 抽取过程知识、collar-specs 比对代码与 spec 偏离，使知识沉淀从“靠自觉”变成流程门禁。 单人攻坚一个月后项目加人，团队借鉴 Web2.0 站点地图思路，用 docs/specs/ 按业务地图横向铺开分区：00_[站点设计]、01_管理端（16 个功能模块）、02_用户端（6 个）、03_小二端（14 个）、04_专家端（1 个）、05_评测端（2 个），数字前缀保证目录有序；每位同学进场前先确认自己负责的产品前台路由、后台 API 领域、产品模块与 spec 范围，边界之外的协同必须与项目组对焦。每次变更归入四种类型：feature（正式规格）、patch（挂在 feature 下的补丁，主 spec 稳定后才收敛，案例中“创建访谈”累积到 PATCH-011）、sunset（日落，带状态机的可执行迁移剧本，如 V1 自建 LLM Agent 自 2026-05-26 迁移到算法团队 TPP 服务后进入凝固期）、blueprint（放在 docs/wiki/blue-print/ 的成熟度阶梯，从 [调研]→[讨论稿]→[技术方案] 毕业后才迁入 specs）。patch 的关键设计是双向指针：补丁开头声明覆盖范围，主文档对应段落加删除线与 superseded 指针，且补丁必须可独立阅读，使 Agent 从任一文件切入都能拼出当前生效真相。 多人协作到一定阶段，团队为发布效率把硬编码的提示词逻辑迁移到 Prompt 工作台、Diamond、DB 等外部介质，结果 Agent 读代码只能看到 promptService.load(agentCode) 的调用框架，推理链断裂、会在关键决策上误判。项目组由此立下原则：“任何导致上下文异常的研发架构变动，都必须用适合的方式缝补缺损的上下文。”具体做法是为 MDI 提供专属 MCP Server，暴露 20 个只读查询工具，其中第 7 组「Prompt 工程」提供 query_prompt_manifest（按场景码+Agent 码返回当前生效 promptId/version/激活环境）、query_prompt_content（取完整 Mustache 模板与变量名、模型名）、query_prompt_versions、query_prompt_intermediates（每个 Agent 实际输入输出与耗时）四类能力；同时配一个 Skill 作为该 MCP 的“使用说明书”，明确何时查、怎么查（四步调用链）、查到后怎么用。另有两个同思路案例：预发/线上环境差异在 AGENTS.md 关键约定速查里显式声明并沉淀为 ADR；外置到 Transform 平台的 Groovy 脚本用 //! 声明式注释把名称、风险、参数、可运行环境等锚点保留在源码中。 每周一个大版本、预发同时十几个分支的高速迭代期（最夸张一次上线同时存在八个仓库、十几个分支），团队先做了一次失败尝试：nekocollar-app 监听 cursor/qoder/claude code 进程输入输出做“编码态监控”，因本地过程态噪音极多、信噪比极低且 token 成本过高而失败；复盘后把介入时机从编码态后移到预发集成态，做了 collar-daemon——一台跑在独立机器（目标形态 Mac mini）上、纯原生 Node.js 零第三方依赖的长驻守护进程，按 600s（线上）/300s（预发）轮询各子仓，预发侧用 git for-each-ref 按 committerdate 倒序自动发现各仓最新 release 分支并物理同步到同一工作区，还原出“谁的开发机都没有的”预发合并态快照。daemon 自身不做规则判断、不内联 prompt，只把每个新提交的作者、message、变更文件按仓库分组 POST 给云端 QoderWake Automation Agent 判定冲突，命中则钉钉群告警并写入 AI 表格做状态流转（问题存在/误报/已修复）。北极星指标为周冲突有效发现率。实际成效：业务冲突有效发现率稳定超过 70%（相较本地编码态方案从“不可用”翻到八成命中），每周能发现 40+ 个真实的多人研发潜在问题；还用 net.Server 双向 pipe 做同端口不同 IP 的透明转发，把硬编码 127.0.0.1 的 QoderWake 管理界面暴露到内网供全团队访问。 稳定运作期团队开发 NekoCollar，把 AI 编码能力开放给不懂代码、不懂 git 的非研发角色。效率线：WorkspaceProvisionOrchestrator 用 @Async 五步流水线在 Aone 沙箱一键拉起环境（CreateInstance → CREATING_SANDBOX → INSTALLING_CLI 装 claude-cli → PrepareWorkdir，先 clone 知识库作外层目录再把代码仓 clone 进知识库内部 → INJECTING_HISTORY 恢复对话记忆 → STARTING_BRIDGE → CONNECTING_AGENT）；并在沙箱内跑真实的 npm run start dev server，通过 Aone Sandbox SDK 把端口映射为外部 URL 后注册到 NekoCollar，再由 nekocollar-extension 浏览器插件动态注入重定向规则，把预发/线上真实页面从 g.alicdn.com/dev.g.alicdn.com 加载的前端资源实时代理到沙箱 endpoint（仅在该插件生效、限定当前标签页、20 秒 TTL 缓存 + 轮询刷新），使产品/设计在真实页面上即时看到 AI 编辑结果。稳定性线已真实落地两道锁：clone 后遍历所有仓库把 push URL 改写为 PUSH_DISABLED 的协议层硬锁（任何 git push 直接 fatal 失败），以及 Claude Code permissions.allow 白名单只放行 fetch/pull/merge/rebase/checkout/add/status/log/diff 等拉取类命令的行为层软锁；服务端接口改动则用浏览器插件 mock 就地拦截，提案（Proposal）机制与角色运行时鉴权仍在开发中。