Back to Details

write-context-rules

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

write-context-rules

write-context-rules

RULES.md
is loaded with every message to the nao agent — keep it lean. Two purposes only:
  1. Orchestrator — point the agent to the right context fast (which metric → which table, which topic → which file, which question type → which skill).
  2. Broad rules — how to query and how to answer.
Anything else (per-table schema, full metric semantics, domain-specific rules) belongs in a referenced file: 
databases/<table>.md
, 
semantics/<metric>.yaml
, or a domain 
.md
. Reference: docs.getnao.io/nao-agent/context-builder/rules-context.
RULES.md
会在每次向nao agent发送消息时加载——请保持内容精简。它仅具备两个用途：
  1. 编排器——快速引导agent找到正确的上下文（哪个指标对应哪个表，哪个主题对应哪个文件，哪种问题类型对应哪个skill）。
  2. 通用规则——查询方式与回答规范。
其他所有内容（每张表的 schema、完整的指标语义、领域特定规则）都应放在引用文件中：
databases/<table>.md
、
semantics/<metric>.yaml
或领域相关的
.md
文件。参考文档：docs.getnao.io/nao-agent/context-builder/rules-context。

Standard sections (see 
templates/RULES.md
)

标准章节（详见
templates/RULES.md
）

  1. ## Business overview
    — Product + Business model.
  2. ## Data architecture
    — Warehouse, data stack, layers, sources.
  3. ## Core data models
    — 
    ### Most Used Tables
    (one-line pointers) + 
    ### Tables detail
    (Purpose / Granularity / Key Columns ≤10 / Use For).
  4. ## Key Metrics Reference
    — grouped by category; 
    **metric** → table, column, formula
    .
  5. ## Date filtering
    — three example formulas (last X weeks / last X days / current month). Don't enumerate every period.
  6. ## Analysis Process
    — 5 subsections: Understand → Select Table → Write Query → Validate → Context.
  1. ## Business overview
    — 产品+商业模式。
  2. ## Data architecture
    — 数据仓库、数据栈、数据层、数据源。
  3. ## Core data models
    — 
    ### Most Used Tables
    （单行指向说明） + 
    ### Tables detail
    （用途/粒度/关键列≤10个/适用场景）。
  4. ## Key Metrics Reference
    — 按类别分组；格式为
    **metric** → table, column, formula
    。
  5. ## Date filtering
    — 三个示例公式（最近X周/最近X天/当月）。无需枚举所有时间周期。
  6. ## Analysis Process
    — 5个子章节：理解→选择表→编写查询→验证→上下文。

Flow

流程

Generate section by section. Write each section to 
RULES.md
, show the user, then move on. Don't read everything and write everything in one batch — the user needs to see progress and catch wrong inferences early.
If 
RULES.md
already has content, run the audit-and-fill flow at the bottom instead.
逐章节生成。将每个章节写入
RULES.md
，展示给用户后再进行下一章节。不要一次性读取所有内容并完成全部编写——用户需要看到进度，尽早发现错误推断。
如果
RULES.md
已有内容，请改用底部的审计填充流程。

Step 1 — 
## Business overview

步骤1 — 
## Business overview

Sources: web search for the company name/domain (from 
nao_config.yaml
), then 
databases/
and 
repos/<dbt>/
. Output two paragraphs: Product (what the company does) + Business model (revenue + customer journey).
数据源：从
nao_config.yaml
获取公司名称/域名后进行网页搜索，再结合
databases/
和
repos/<dbt>/
中的内容。输出两段内容：产品（公司业务内容）+商业模式（收入+客户旅程）。

Step 2 — 
## Data architecture

步骤2 — 
## Data architecture

From 
databases/
and 
repos/<dbt>/
: Warehouse type/project/dataset, Data stack (e.g. 
dlt, dbt, no semantic layer
), Data layers (e.g. 
bronze / silver / gold
), Data sources (numbered list with prefix + one-line description).
从
databases/
和
repos/<dbt>/
中提取：数据仓库类型/项目/数据集、数据栈（例如
dlt, dbt, no semantic layer
）、数据层（例如
bronze / silver / gold
）、数据源（带前缀的编号列表+单行描述）。

Step 3 — 
## Core data models

步骤3 — 
## Core data models

### Most Used Tables
 — one line per in-scope table:
- `dim_users` — user dimension. See `databases/.../table=dim_users/`.
### Tables detail
 — per-table block: Purpose, Granularity, Key Columns (cap at 10), Use For. Per-table detail beyond top 10 columns lives in 
databases/
, not here.
### Most Used Tables
 — 每个范围内的表对应一行：
- `dim_users` — 用户维度表。详见`databases/.../table=dim_users/`。
### Tables detail
 — 每张表的信息块：用途、粒度、关键列（最多10个）、适用场景。前10列之外的表详情请放在
databases/
中，不要写在这里。

Step 4 — 
## Key Metrics Reference

步骤4 — 
## Key Metrics Reference

Group by category (Revenue / Activity / Conversion). Format:
undefined
按类别分组（收入/活跃度/转化率）。格式示例：
undefined

Revenue

Revenue

  • MRR → 
    fct_stripe_mrr.mrr_amount
    , 
    SUM(mrr_amount) WHERE status='active'

If a semantic layer is configured (`add-semantic-layer`), route through it: `**ARR** → query via dbt MCP query_metric (semantic layer)`.
  • MRR → 
    fct_stripe_mrr.mrr_amount
    , 
    SUM(mrr_amount) WHERE status='active'

如果已配置语义层（`add-semantic-layer`），则通过语义层查询：`**ARR** → query via dbt MCP query_metric (semantic layer)`。

Step 5 — 
## Date filtering
(placeholder until Step 7)

步骤5 — 
## Date filtering
（占位，待步骤7填充）

Leave a 
> TODO: filled in via the user-validation step below.
Filled in Step 7.
留下
> TODO: 后续通过下方的用户验证步骤填充。
，在步骤7中完成填充。

Step 6 — 
## Analysis Process

步骤6 — 
## Analysis Process

Use the template's 5 subsections verbatim. The project-specific bit is subsection 2 (Select Right Tables): map each major question category to its starting table, derived from Steps 3-4.
直接使用模板中的5个子章节内容。项目特定部分是第2小节（选择正确的表）：将每个主要问题类别映射到其起始表，此映射源自步骤3-4的内容。

Step 7 — Validate metrics with the user

步骤7 — 与用户验证指标

For each metric in 
## Key Metrics Reference
, ask the user to confirm or correct the source-of-truth pointer. Update in place.
针对
## Key Metrics Reference
中的每个指标，请用户确认或更正真实数据源的指向。直接在原位置更新内容。

Step 8 — Date filtering, with the user

步骤8 — 与用户确认日期过滤规则

Two questions decide most of it:
  1. Week boundary: does a week start Sunday (BigQuery 
    WEEK
    ) or Monday (
    ISOWEEK
    )? Applies to "last week", "last N weeks", week-over-week.
  2. Current period inclusion: when the user says "last 8 weeks" / "last 30 days", include the current incomplete period or exclude it? Rolling-from-now vs. boundary-aligned.
Then: fiscal year start if non-calendar; anything else org-specific.
Write three example formulas only — Last X weeks, Last X days, Current month. The agent extrapolates other periods from these. Each block gets a one-line note above stating the convention used.
sql
-- Last X weeks (Monday-start, excludes current incomplete week)
WHERE date >= DATE_TRUNC(CURRENT_DATE - INTERVAL (X * 7) DAY, ISOWEEK)
  AND date <  DATE_TRUNC(CURRENT_DATE, ISOWEEK)
两个问题可确定大部分规则：
  1. 周边界：一周从周日（BigQuery 
    WEEK
    ）还是周一（
    ISOWEEK
    ）开始？适用于“上周”、“最近N周”、周环比场景。
  2. 当前周期是否包含：当用户说“最近8周”/“最近30天”时，是否包含当前未完成的周期？即从当前时间往前滚动，还是按边界对齐。
此外：如果财年起始日非自然年，请确认；以及其他组织特定规则。
仅编写三个示例公式——最近X周、最近X天、当月。agent会根据这些示例推导出其他时间周期的规则。每个公式块上方添加一行说明，注明所使用的规则约定。
sql
-- Last X weeks (Monday-start, excludes current incomplete week)
WHERE date >= DATE_TRUNC(CURRENT_DATE - INTERVAL (X * 7) DAY, ISOWEEK)
  AND date <  DATE_TRUNC(CURRENT_DATE, ISOWEEK)

Audit-and-fill flow (when 
RULES.md
is not empty)

审计填充流程（当
RULES.md
不为空时）

  1. Read it. Compare against the six standard sections. Produce a one-line gap report (present / missing / thin per section).
  2. Ask the user which sections to fill.
  3. Run only the relevant generation steps above. Show diffs before saving.
For deeper diagnostics (MECE, schema drift, test failure root causes), route to 
audit-context
.
  1. 读取现有内容，与六个标准章节对比，生成一行差距报告（每个章节的状态：已存在/缺失/内容单薄）。
  2. 询问用户需要填充哪些章节。
  3. 仅运行上述相关的生成步骤。保存前展示差异内容。
如需更深入的诊断（MECE、schema漂移、测试失败根本原因），请转至
audit-context
。

Guardrails

约束规则

  • Section by section, not all-at-once. Show progress, let the user course-correct.
  • Show diffs, don't auto-overwrite.
  • Don't bloat 
    RULES.md
    .     Per-table detail in 
    databases/<table>.md
    .
  • Don't invent metric sources. Unclear → list for user validation in Step 7.
  • ## Date filtering
    keeps three examples max.
  • 逐章节进行，而非一次性完成。展示进度，让用户可以及时调整方向。
  • 展示差异，不要自动覆盖。
  • 不要让
    RULES.md
    内容臃肿    。每张表的详情请放在
    databases/<table>.md
    中。
  • 不要编造指标数据源。若信息不明确，请在步骤7中列出供用户验证。
  • ## Date filtering
    最多保留三个示例    。

Templates

模板

  • templates/RULES.md
    — six-section scaffold. This skill is the only one that writes to 
    RULES.md
    .
  • templates/RULES.md
    — 包含六个章节的框架。本skill是唯一可写入
    RULES.md
    的功能。