企业官网建设流程全解析

• AI Agent
• Agent 工作流
• 开发工具

Agent OS 的核心能力之一Discover Standards，负责把散落在代码库各处的"隐性知识"（tribal knowledge）——那些新开发者不看代码就永远不知道的约定——提炼成简洁、可被 AI 直接检索与注入的工程标准文档。本文以 commands/agent-os/discover-standards.md 为骨架，结合 index-standards.md、inject-standards.md 以及 scripts 目录下的安装、同步脚本，完整讲解从代码分析、交互确认、标准起草到索引更新、跨项目复用的六步工作流。读完本文，你将掌握如何在项目中运行/discover-standards，产出一套"AI 友好、token 高效"的团队规范，并与/inject-standards形成自动化的规范注入闭环。

一、Discover Standards 在 Agent OS 中的定位

Agent OS（仓库 README.md）是一套让 AI 编程助手"按照你的方式写代码"的轻量级框架，可配合 Claude Code、Cursor 等工具使用。它的核心能力矩阵是：

• Discover Standards：从代码库中提取模式与约定，沉淀为文档化标准；
• Deploy Standards（Inject Standards）：根据你正在做的事情，智能注入相关标准；
• Shape Spec：创建更好的计划，导向更好的构建；
• Index Standards：保持标准有序、可发现。

Discover Standards 正是整个体系的"源头"：它把代码库中实际存在、反复出现、但从未被写下来的约定，变成显式的 Markdown 标准文件。据 CHANGELOG.md 记载，/discover-standards是 Agent OS v3（2026-01-20 发布）新增的核心工具，它让 Agent 能够从你的代码库中提出（surface）、建议（suggest）并创建（create）标准。v3 的定位是"聚焦建立标准与注入标准"，而把 spec 编写、任务拆分等能力让位给现代 AI 工具自带的 Plan Mode，因此 Discover Standards 在 v3 中的地位尤为突出。

一句话概括它的价值：代码里已有的约定值得被记录，而记录下来的约定值得被 AI 严格执行。

二、运行前必读的三条铁律

原文档 discover-standards.md 在正文开头给出了三条硬性准则，它们决定了整个流程的交互方式与产出质量：

1. 始终使用 AskUserQuestion 工具：任何需要向用户提问的场景，都必须通过 AskUserQuestion 工具完成，而不是在对话里直接抛出开放式问题。这保证了交互是有结构、可选择的（AskUserQuestion 是 Claude Code 等 AI 编程助手内置的结构化提问能力，能够让用户在选项卡片上直接确认或修改，见 CHANGELOG.md 中 "Product planning phase streamlined with AskUserQuestion tool integration" 的说明）。
2. 写出简洁的标准：用最少的词。标准会被注入 AI 的上下文窗口，必须能被 AI Agent 快速扫读，同时不能撑爆上下文窗口。每个词都是 token，每个 token 都是成本。
3. 提供建议而非空问：给用户呈现可确认、可选择、可纠正的选项，不要让他们做不必要的思考。Agent 的工作是把决策成本降到最低，而不是把问题抛回给用户。

这三条准则贯穿后面全部六个步骤，尤其是"先给结论/建议，再让用户确认或修正"的交互模式。

三、六步工作流：从分析代码库到生成标准文件

Discover Standards 的完整流程包含六个步骤。下面按原文档顺序逐一展开，并补充仓库源码层面的机制说明。

Step 1：确定焦点领域

第一步是确定"我们要从哪个领域挖掘标准"。

如果用户在运行命令时已经指定了领域，直接跳到 Step 2。如果没有指定，则：

1. 分析代码库结构（文件夹、文件类型、代码模式）；
2. 识别出 3～5 个主要领域。原文档给出的分类示例：
   • 前端领域：UI 组件、样式/CSS、状态管理、表单、路由；
   • 后端领域：API 路由、数据库/模型、认证、后台任务；
   • 横切关注点：错误处理、校验、测试、命名约定、文件结构；
3. 用 AskUserQuestion 向用户呈现这些领域，例如：

I've identified these areas in your codebase: 1. **API Routes** (src/api/) — Request handling, response formats 2. **Database** (src/models/, src/db/) — Models, queries, migrations 3. **React Components** (src/components/) — UI patterns, props, state 4. **Authentication** (src/auth/) — Login, sessions, permissions Which area should we focus on for discovering standards? (Pick one, or suggest a different area)

在继续之前必须等待用户响应。这里的关键点是：领域选择权在用户，Agent 只负责"扫描并提议"。这一设计避免了 Agent 擅自决定关注点而偏离团队实际诉求。

Step 2：分析并呈现发现

领域确定后，进入代码分析阶段：

1. 读取该领域的关键文件（5～10 个代表性文件）；

2. 寻找符合以下特征的模式：

   • 非常规（Unusual or unconventional）——不是框架/库的标准用法，而是项目自己的特殊处理；
   • 有主见（Opinionated）——本可以有多种做法、但项目明确选择了某一种；
   • 隐性知识（Tribal）——新开发者不被告知就绝对不会知道的东西；
   • 一致（Consistent）——在多个文件中反复出现的相同模式。

   同时满足"有主见 + 一致"的模式，通常就是最值得沉淀为标准的东西：它们既是团队刻意选择，又被大面积使用，一旦写错代价很高。

3. 用 AskUserQuestion 呈现发现，让用户勾选要沉淀的候选标准：

I analyzed [area] and found these potential standards worth documenting: 1. **API Response Envelope** — All responses use { success, data, error } structure 2. **Error Codes** — Custom error codes like AUTH_001, DB_002 with specific meanings 3. **Pagination Pattern** — Cursor-based pagination with consistent param names Which would you like to document? Options: - "Yes, all of them" - "Just 1 and 3" - "Add: [your suggestion]" - "Skip this area"

等待用户选择后再继续。注意选项里永远留了三条退路：全选、部分选、补充建议、跳过该领域——这正是"Offer suggestions"铁律的具体落地。

Step 3：先问"为什么"，再逐条起草每项标准

这是整个流程中最容易做错、也最影响质量的一步。原文档用粗体强调：对于每一项被选中的标准，必须完成完整的循环后才能进入下一项：

1. 针对该模式背后的"为什么"提出 1～2 个澄清问题（用 AskUserQuestion）；
2. 等待用户回答；
3. 将用户回答融入标准草稿；
4. 在创建文件前与用户确认；
5. 获批准后创建文件。

示例提问（根据具体标准调整）：

• "这个模式解决了什么问题？为什么不用默认/常规做法？"
• "有没有不应该使用这个模式的例外情况？"
• "开发者或 Agent 在这上面最容易犯的错误是什么？"

严禁把所有问题一次性全部抛出。一次只处理一项标准，走完完整的"提问 → 等待 → 起草 → 确认 → 建文件"循环，再开始下一项。

这一步的价值在于：标准文档记录的不只是"怎么做"，更是"为什么这么做"。理解了动机，AI Agent 在面对新场景时才能判断"这条标准该不该套用"，而不是机械照搬。

Step 4：创建标准文件

每一项标准在完成 Step 3 的问答后，按以下流程落盘：

1. 确定归属文件夹（不存在则创建），原文档给出的可选目录包括：api/、database/、javascript/、css/、backend/、testing/、global/；
2. 检查是否已有相关标准文件——如果有，追加到已有文件而非新建，避免标准碎片化；
3. 起草内容并用 AskUserQuestion 确认，原文档给出了标准的草稿模板：

Here's the draft for api/response-format.md: --- # API Response Format All API responses use this envelope: ```json { "success": true, "data": { ... } } { "success": false, "error": { "code": "...", "message": "..." } }

• Never return raw data without the envelope
• Error responses must include both code and message
• Success responses omit the error field entirely

Create this file? (yes / edit: [your changes] / skip)

4. 创建或更新文件，路径为 `agent-os/standards/[folder]/`； 5. **然后对下一项选中的标准重复 Step 3～4**。 注意草稿模板本身就是一个"标准标准"的范本：标题一句话说清主题，代码块展示事实，三条 bullet 分别说明边界（不做什么）、必选项（做什么）、可选项（什么情况下省略什么）。后面第五节会专门拆解这种写法。 ### Step 5：更新索引 所有标准创建完毕后，更新索引 `agent-os/standards/index.yml`： 1. 扫描 `agent-os/standards/` 下所有 `.md` 文件； 2. 对每个没有索引条目的新文件，用 AskUserQuestion 提议描述文案：

New standard needs an index entry: File: api/response-format.md

Suggested description: "API response envelope structure and error format"

Accept this description? (yes / or type a better one)

3. 更新 `agent-os/standards/index.yml`： ```yaml api: response-format: description: API response envelope structure and error format

排序规则：先按文件夹名、再按文件名，一律字母序。

索引文件是整个体系的关键枢纽。正如 index-standards.md 开头所解释的：索引让/inject-standards无需读取全部标准文件即可推荐相关标准——它把每个标准映射为一句简短描述，供快速匹配使用。换句话说，索引是"标准目录的目录"。

关于索引还有两个从 index-standards.md 补充的关键细节：

• root是保留字：指直接位于agent-os/standards/根目录下的.md文件（不在子文件夹中），不要创建名为 root 的实际文件夹；
• 索引条目的描述必须保持一句话——它是用于匹配的，不是文档。

而 project-install.sh 中的create_index()函数（第 278～382 行）展示了该索引在实际安装时的生成逻辑：脚本扫描根目录与子文件夹的.md文件，优先复用旧索引中已有的description，对没有描述的条目写入占位符"Needs description - run /index-standards"——这正是 /discover-standards 和 /index-standards 需要介入补全描述的地方。

Step 6：提供继续选项

最后一步，用 AskUserQuestion 询问用户是否继续：

Standards created for [area]: - api/response-format.md - api/error-codes.md Would you like to discover standards in another area, or are we done?

这一步把流程设计成一个"可循环"的开放闭环：一个领域完成后，用户可以立即转向下一个领域（回到 Step 1），也可以就此结束。

四、输出位置与目录约定

所有产出的标准统一落在两个位置：

所有标准： agent-os/standards/[folder]/[standard].md 索引文件： agent-os/standards/index.yml

这套目录约定与仓库的 profile 机制相互呼应。仓库中 profiles/default/global/tech-stack.md 展示了"标准按领域目录组织"的既有形态：global/目录存放跨领域通用标准（如 tech-stack）。当通过 project-install.sh 把默认 profile 安装进项目时，profile 内standards/下的所有.md文件（排除.backups/目录，见 common-functions.sh 的copy_standards()函数）会被原样复制到项目的agent-os/standards/中，/discover-standards再在此基础上增量追加新发现的标准。

这种"profile 提供基线标准 + discover 发现项目特有标准"的组合，保证了每个项目的agent-os/standards/既是自包含的（可提交进仓库供团队共享），又能持续生长出项目自己的约定。

五、写出"每个字都值钱"的简洁标准

原文档在 Writing Concise Standards 一节 给出了为什么必须简洁的根本原因：

Standards will be injected into AI context windows. Every word costs tokens.

标准会被注入 AI 上下文窗口，每个词都消耗 token。结合 inject-standards.md 可以看到，标准在实际使用中会被整篇读入对话上下文（Conversation 场景）、嵌入 Claude Skill 或计划文档——因此冗长的标准会直接推高每次任务的 token 成本，并稀释 AI 对关键信息的注意力。

为此，写标准必须遵循五条规则：

• 规则先行（Lead with the rule）——先说该怎么做，再说为什么（如需）；
• 用代码示例（Use code examples）——展示胜于讲述；
• 跳过显而易见的（Skip the obvious）——不要记录代码本身已经说清楚的东西；
• 一个概念一条标准（One standard per concept）——不要把不相关的模式揉在一起；
• 用列表代替段落（Bullet points over paragraphs）——可扫读性优先于可读性。

原文档给出了正反两个对照，非常直观。好标准长这样：

# Error Responses Use error codes: `AUTH_001`, `DB_001`, `VAL_001` ```json { "success": false, "error": { "code": "AUTH_001", "message": "..." } }

• Always include both code and message
• Log full error server-side, return safe message to client

**坏标准**长这样（原文以"[continues for 3 more paragraphs]"示意其冗长）： ```markdown # Error Handling Guidelines When an error occurs in our application, we have established a consistent pattern for how errors should be formatted and returned to the client. This helps maintain consistency across our API and makes it easier for frontend developers to handle errors appropriately... [continues for 3 more paragraphs]

对比可见：好标准 4 行文字 + 1 段 JSON 就把"用什么错误码、响应长什么样、必须包含什么、哪边记日志哪边回消息"全部讲完；坏标准写了三段话还没给出任何可执行的信息。前者是 AI 能"一眼执行"的标准，后者是 AI 读完还要自己提炼的散文。

六、完整示例：一条标准从发现到落盘

原文档用一整节演示了单条标准走完整套工作流的全过程，这里完整复现并加注说明：

1. 呈现发现（Step 2）：

I found these patterns in your API code: 1. **Response Envelope** — All responses use { success, data, error } 2. **Error Codes** — Custom codes like AUTH_001 Which would you like to document?

用户回复："Both"

2. 为第一条标准问"为什么"（Step 3）：

For the Response Envelope pattern: - What problem does this solve? Why not return raw data? - Are there any endpoints that don't use this pattern?

用户回复："We use it so the frontend always knows where to find the data. All endpoints use it, no exceptions."

3. 起草第一条标准（Step 3 续）：

Here's the draft for api/response-envelope.md: --- # Response Envelope All API responses use this structure: ```json { "success": true, "data": { ... } } { "success": false, "error": { ... } }

• Frontend always checkssuccessfirst, then readsdataorerror
• No exceptions — every endpoint uses this format

Create this file?

用户回复："Yes" **4. 创建文件，然后处理下一条标准：**

[Create the file]

**5. 为第二条标准问"为什么"（回到 Step 3）：**

For the Error Codes pattern:

• What's the naming convention for codes?
• Where should new error codes be documented?

用户回复："Format is AREA_NUMBER like AUTH_001. We keep a list in the wiki." **6. 起草第二条标准、确认、创建文件……**

[Continue until all selected standards are done]

原文档最后强调的关键点：**每条标准都要完整走完"提问 → 起草 → 确认 → 创建"循环，再开始下一条**。注意示例中两条标准的问题各不相同——第一条追问"为什么不用默认做法、有没有例外"，第二条追问"命名规范、在哪里登记"——提问必须贴合该模式的具体决策点，而不是套用模板。 ## 七、安装与标准目录的落地：脚本视角 要让 `/discover-standards` 在你的项目里跑起来，前提是项目已完成 Agent OS 安装。结合仓库脚本可以看清标准系统的完整落地链路： **1. 安装（[project-install.sh](https://link.gitcode.com/i/66312ba1434a9b3245cc11f77ef331c7)）** - 在项目根目录运行安装脚本，常用参数：`--profile <name>` 指定使用哪个 profile（默认取 [config.yml](https://link.gitcode.com/i/f3040a8241ebc789e76e9d33f022c16a) 中的 `default_profile`，当前值为 `default`）、`--commands-only` 只更新命令不动已有标准、`--verbose` 输出详细日志； - 脚本会创建 `agent-os/standards/` 目录结构，把 profile 的标准复制进来，并自动生成 `index.yml`； - 命令文档被安装到项目的 `.claude/commands/agent-os/` 下，`/discover-standards` 即由此提供（对应仓库 [commands/agent-os/](https://link.gitcode.com/i/651315313866d4961c1725b566552cc0) 目录）； - 安装完成后脚本提示的两个"Next steps"正是：先跑 `/discover-standards` 提取代码库模式，再跑 `/inject-standards` 将标准注入上下文。 **2. 配置（[config.yml](https://link.gitcode.com/i/f3040a8241ebc789e76e9d33f022c16a)）** ```yaml version: 3.0 default_profile: default # Optional: define inheritance relationships for profiles # profiles: # profile-a: # inherits_from: default # profile-b: # inherits_from: profile-a

default_profile决定安装时默认使用的标准基线；profiles下的inherits_from支持 profile 继承链（common-functions.sh 中的get_profile_inheritance_chain()会解析该链并检测循环依赖）。

3. 回灌（sync-to-profile.sh）

/discover-standards发现的标准沉淀在项目agent-os/standards/后，可以通过同步脚本回灌到 base profile，供其他项目复用：

./scripts/sync-to-profile.sh # 交互式选择 profile 与文件 ./scripts/sync-to-profile.sh --profile rails # 直接同步到指定 profile ./scripts/sync-to-profile.sh --all --overwrite # 全量同步并覆盖（自动备份） ./scripts/sync-to-profile.sh --new-profile nextjs --all # 同步到新 profile

脚本会做冲突检测：目标 profile 已存在同名文件时，可选择"带备份覆盖 / 跳过 / 取消"，备份存放在 profile 的standards/.backups/<时间戳>/下（common-functions.sh 的copy_standards()在复制时同样排除了.backups/）。

这套"安装 → 发现 → 索引 → 注入 → 回灌"的闭环，让标准既能在单个项目内被 AI 严格执行，又能跨项目沉淀为团队资产。

八、工作流全景：discover → index → inject 的闭环

最后把 Discover Standards 放到整个 Agent OS 体系中看它的上下游：

• 上游（输入）：代码库本身 + 用户的领域选择。Discover Standards 从中提取模式；
• 中游（产物）：agent-os/standards/[folder]/[standard].md标准文件 +agent-os/standards/index.yml索引；
• 下游（消费）：inject-standards.md 读取index.yml，根据当前任务上下文（对话、创建 Skill、Plan Mode 规划）匹配 2～5 条相关标准并注入；shape-spec.md 在规划阶段也会调用/inject-standards把相关标准带入 spec。

需要特别指出的是，/discover-standards会在最后一步自动执行索引更新。正如 index-standards.md 明确说明的："/discover-standardsruns this automatically as its final step, so you usually don't need to call it separately after discovering standards." 也就是说，正常跑完 /discover-standards，Step 5 的索引更新已经内嵌完成；独立的/index-standards命令主要用于以下场景：手动创建/删除标准文件之后、/inject-standards的推荐出现错位时、或索引长期未维护需要重建时。

由此可以归纳出与/discover-standards配套的三个最佳实践：

1. 在任务开始时尽早发现标准：先沉淀标准，再让/inject-standards在每次任务中自动带上它们，避免每次开发都重复"口述约定"；
2. 保持标准单条聚焦、每条极简：标准是被注入到上下文里消费的，简洁直接决定 AI 的执行准确率与 token 成本；
3. 让发现成为习惯：每当代码库出现新的稳定模式，就运行一次/discover-standards（或手动补一条标准再跑/index-standards），让agent-os/standards/始终与代码库的真实约定保持同步。

最终，Discover Standards 达成的效果是：团队的工程约定不再依赖"老员工口口相传"，而是以可检索、可注入、可跨项目复用的标准文件形式，成为 AI 与新人开发者都能直接执行的第一手资料。

• AI Agent
• Agent 工作流
• 开发工具