如何让 AI 长期理解这个项目，知道哪些事情绝对不能做，知道不同场景应该遵循什么规则，并且即使换一个模型、换一个 Agent，项目的核心知识和工程约束也不会丢失。因此我们先从整体体系结构设计上推荐如下：

项目知识
    ↓
AGENTS.md
    ↓
业务规则 / 架构 / 数据契约 / 安全规范
    ↓
Rules
    ↓
Skills
    ↓
Sub-Agents
    ↓
Tests / CI / Hooks / Runtime Guards
    ↓
生产代码

一句话就是说：AI 文件负责告诉 Agent 应该怎么做；测试、CI、Hook 和系统约束负责确保它真的这么做。

一、为什么普通的 AGENTS.md 不够

对于气象数据平台而言，用的哪些技术不重要，项目最重要的业务规则是什么更加重要！比如：

原始观测数据能不能修改？
AI 能不能生成天气实况？
预报数据能不能当观测数据？
公开网页上的数据能不能直接抓？
异常数据应该删除还是标记？
温度单位到底是什么？
时间到底使用 UTC 还是北京时间？
一个数据到底从哪里来的？
数据导出以后是否允许再次分发？

• AGENTS.md 应该是 Agent 进入项目后的第一张地图

二、推荐的 AI Native 项目知识体系

一个本人用起来顺手的国内气象数据平台体系结构如下：

weather-platform/
│
├── AGENTS.md #项目总览、核心原则、导航
│
├── docs/
│   ├── architecture.md   #架构
│   ├── business-rules.md #业务
│   ├── data-contracts.md #数据结构规范
│   ├── database.md       #数据库模型规范
│   ├── api-spec.md。     #API规范
│   ├── development-guide.md
│   │
│   └── adr/ #为什么这么设计
│       ├── 0001-timezone.md
│       ├── 0002-raw-data-immutable.md
│       ├── 0003-api-format.md
│       ├── 0004-timeseries-storage.md
│       └── 0005-ai-data-boundary.md
│
├── .ai/
│   ├── coding-rules.md
│   ├── testing-rules.md
│   └── security-rules.md
│
├── .cursor/
│   ├── rules/ #业务场景自动加载规范
│   │   ├── 00-core.mdc
│   │   ├── 10-weather-domain.mdc
│   │   ├── 20-data-quality.mdc
│   │   ├── 30-api.mdc
│   │   ├── 40-database.mdc
│   │   ├── 50-security.mdc
│   │   └── 80-testing.mdc
│   │
│   ├── skills/ #某类业务的标准化操作和流程
│   │   ├── qc-rule-writer/
│   │   ├── data-source-onboarding/
│   │   ├── api-designer/
│   │   ├── database-migration/
│   │   └── weather-pr-review/
│   │
│   └── agents/ #审查
│       ├── qc-auditor.md
│       ├── data-governance-auditor.md
│       ├── security-auditor.md
│       └── api-compliance-auditor.md
│
└── tests/ #测试验证
    └── contracts/

三、AGENTS.md：项目的 AI 总说明书

AGENTS.md最重要的任务是：

1. 告诉 AI 项目是什么
2. 告诉 AI 最重要的原则
3. 告诉 AI 去哪里找详细规则
4. 告诉 AI 哪些事情绝对不能做
5. 告诉 AI 修改代码之前应该做什么

## 1. 项目概览

本项目是一个面向中国境内气象数据场景的 AI Native 气象数据平台。

平台核心能力：

- 多源气象数据接入
- 数据标准化
- 数据质量控制
- 气象站点管理
- 历史数据管理
- 实况数据服务
- 预报数据服务
- 气象灾害信息服务
- 数据 API
- 数据查询与导出
- 地图可视化
- 数据分析
- AI 气象问答
- AI 数据分析
- AI 辅助预测

项目的核心原则：

data credibility
>
traceability
>
security/compliance
>
data quality
>
correctness
>
availability
>
performance
>
feature velocity

---

## 2. 技术栈

当前技术栈以实际项目配置为准。

可能包括：

- Backend: Spring Boot
- Frontend: Vue 3 + TypeScript
- Database: relational database
- Cache: Redis
- Time-series storage: 根据实际 workload 选择
- Object storage: MinIO / OSS 等
- Data processing: Spark / Flink / Python 等
- Messaging: Kafka / RabbitMQ 等

不要因为 AGENTS.md 中出现某个技术，就默认所有模块都必须使用它。

具体技术选型以：

docs/architecture.md

为准。

---

## 3. 必读文档

### 修改业务逻辑

首先阅读：

docs/business-rules.md

### 修改架构

阅读：

docs/architecture.md

### 修改数据库

阅读：

docs/database.md

### 修改 API

阅读：

docs/api-spec.md

### 修改数据结构

阅读：

docs/data-contracts.md

### 修改安全相关功能

阅读：

.ai/security-rules.md

### 修改测试

阅读：

.ai/testing-rules.md

---

## 4. 规则优先级

发生冲突时：

法律法规
>
监管要求
>
数据授权/合同
>
业务规则
>
数据契约
>
架构决策
>
开发规范
>
AI Agent 自行判断

AI Agent 不得通过自行推断覆盖明确的项目规则。

---

## 5. 数据核心原则

### 原始数据不可覆盖

Raw data 是不可变资产。

任何修正必须通过新版本或派生数据实现。

### 数据必须可追溯

任何生产数据都应该能够回答：

> 这个数据从哪里来的？

### 观测与预报必须分离

至少区分：

- OBSERVATION
- FORECAST
- ANALYSIS
- REANALYSIS
- ESTIMATION
- AI_GENERATED

### AI 不能制造事实

AI 生成的数据不得伪装成：

- 官方观测
- 官方预报
- 官方预警
- 官方发布

---

## 6. 时间原则

气象数据必须明确时间语义。

不要使用没有业务含义的：

time

应该根据实际含义使用：

- observed_at
- issued_at
- valid_at
- ingested_at
- processed_at

内部数据存储原则上使用 UTC。

展示层根据业务场景转换为中国标准时间。

---

## 7. 空间原则

站点必须使用稳定的：

station_id

不得使用站点名称作为唯一标识。

空间数据必须明确：

- latitude
- longitude
- elevation
- coordinate_reference_system

GeoJSON 是 Web/GIS API 的一种交换格式。

不要强制所有内部气象数据都使用 GeoJSON。

---

## 8. 单位原则

气象变量必须有明确单位。

例如：

temperature
wind_speed
pressure
precipitation

不得使用含义模糊的：

temp
wind
value

不得静默改变单位。

---

## 9. AI 使用原则

实时气象事实必须首先查询可信数据源。

推荐流程：

data retrieval
>
data validation
>
deterministic calculation
>
LLM explanation

不要：

LLM memory
>
weather fact

关键统计结果必须由确定性程序计算。

---

## 10. 外部数据原则

公开访问的数据不等于：

- 可以永久保存
- 可以商业使用
- 可以重新分发
- 可以训练模型
- 可以发送给第三方 AI

新增数据源前必须检查：

- provider
- source
- license
- usage scope
- redistribution
- retention
- security

授权不明确的数据不得作为生产核心数据源。

---

## 11. 修改代码前

执行：

1. 理解任务
2. 找到相关模块
3. 阅读相关文档
4. 查看现有实现
5. 查看相关测试
6. 判断数据/安全/API/数据库影响
7. 设计最小修改
8. 实现
9. 测试
10. 更新必要文档

不要一开始就修改代码。

---

## 12. 完成标准

一个任务只有同时满足以下条件才算完成：

- 功能正确
- 测试通过
- 数据语义正确
- 数据血缘没有破坏
- 安全要求满足
- API 没有意外破坏
- 数据库迁移安全
- 必要文档已经更新

---

## 13. 禁止行为

禁止：

- 编造生产气象数据
- 把 AI 数据当成官方数据
- 覆盖 raw data
- 使用魔法数字表示缺测
- 静默改变单位
- 把 forecast 当 observation
- 未授权抓取数据作为生产核心数据源
- 将敏感数据直接发送给外部 AI
- 删除失败测试来“修复”CI
- 未经评估大规模重构

详细规则咱不要往里面放，简明扼要又面面具到，当然还需要不断优化的过程，不是一锤定音

四、Business Rules：业务真相

放在docs/business-rules.md

原始数据不可覆盖

数据必须保留来源

观测与预报必须区分

异常数据不得静默删除

AI 不得冒充官方预报

数据授权不明确不得进入生产

关键统计必须确定性计算

关键是要回答业务上什么是正确，而不是应该做什么，做什么

五、Data Contract：强烈建议增加

别的我不知道，气象数据平台一定要有docs/data-contracts.md

dataset: surface-observation

schema_version: 1.2

station:
  required: true
  type: string

observed_at:
  required: true
  type: datetime
  timezone: UTC

temperature:
  required: false
  type: number
  unit: celsius

relative_humidity:
  required: false
  type: number
  unit: percent

wind_speed:
  required: false
  type: number
  unit: m/s

quality_flag:
  required: true
  type: enum
  values:
    - GOOD
    - SUSPECT
    - BAD
    - MISSING

数据采集
    ↓
Data Contract
    ↓
Schema Validation
    ↓
QC
    ↓
Storage
    ↓
API
    ↓
AI

这样所有的模块围绕同一个数据规范工作，约定大于配置

六、GeoJSON 不应该成为所有气象数据的统一内部格式

气象平台的数据类型非常多：

站点观测
时间序列
格点数据
雷达数据
卫星数据
预报数据
行政区
轨迹
栅格
气候统计

                   Weather Data
                         │
          ┌──────────────┼──────────────┐
          ↓              ↓              ↓
       Time Series      Raster        Vector
          │              │              │
        TSDB          NetCDF/GRIB     GeoJSON
          │              │              │
          └──────────────┼──────────────┘
                         ↓
                    API Contract
                         ↓
                  Web / GIS / AI

GeoJSON 应该是空间数据/API 展示层格式，而不是整个平台的数据底座格式

七、Rules：让 Agent 在正确的场景看到正确的规则

不要把所有规则都：alwaysApply: true否则 Agent 每次写代码都背一大堆无关信息。

.cursor/rules/
├── 00-core.mdc
├── 10-weather-domain.mdc
├── 20-data-quality.mdc
├── 30-api.mdc
├── 40-database.mdc
├── 50-security.mdc
├── 60-java.mdc
├── 70-frontend.mdc
└── 80-testing.mdc

Rule 1：核心项目规则

---
description: "核心项目规则"
alwaysApply: true
---

# Core Rules

## 数据

- Raw data immutable
- Preserve provenance
- Preserve dataset version
- Never use magic numbers for missing values
- Never silently change units

## 气象语义

Always distinguish:

- OBSERVATION
- FORECAST
- ANALYSIS
- REANALYSIS
- ESTIMATION
- AI_GENERATED

## AI

AI must not fabricate real-time weather facts.

Current weather facts must come from trusted data retrieval.

Important calculations must be deterministic.

## Security

Never hardcode secrets.

Never send restricted data to an external AI provider without authorization.

## Changes

Prefer the smallest safe change.

Do not perform unrelated refactoring.

Rule 2：数据质量控制

---
description: "气象数据质量控制规则"
globs:
  - "**/quality/**"
  - "**/qc/**"
  - "**/validator/**"
  - "**/*Quality*.java"
alwaysApply: false
---

# Quality Control Rules

QC must be:

- versioned
- testable
- explainable
- auditable

Recommended checks:

1. Schema validation
2. Missing-value check
3. Physical-range check
4. Temporal consistency
5. Internal consistency
6. Spatial consistency
7. Climatological consistency
8. Neighbor-station consistency
9. Duplicate detection
10. Source quality

Do not delete anomalous data silently.

Prefer:

raw_value
quality_flag
corrected_value
correction_method

A physical-range failure does not automatically mean the observation is scientifically impossible.

Rules should distinguish:

GOOD
SUSPECT
BAD
MISSING
CORRECTED
ESTIMATED

咱们这里没有写任何的数字，气象领域其实有很多阈值，比如温度-50～50℃咱不在这写，他应该成为规则配置，你可以分版本，但他不是一个规则，散落在Agent Prompt 中。

Rule 3：API

---
description: "气象数据 API 开发规范"
globs:
  - "**/controller/**"
  - "**/api/**"
  - "**/endpoint/**"
alwaysApply: false
---

# API Rules

All production APIs must:

- have explicit versioning
- have clear resource semantics
- validate input
- support request IDs
- use consistent error responses
- enforce query limits
- preserve data provenance

Time-series APIs should support:

startTime
endTime

Large exports must use asynchronous jobs.

Do not use a universal 500ms requirement.

Performance requirements must be defined by workload.

Example:

W1:
single-station current observation
P95 < 200ms

W2:
single-city 24h history
P95 < 1s

W3:
national historical export
asynchronous

Rule 4：数据库

---
description: "气象数据数据库规则"
globs:
  - "**/repository/**"
  - "**/mapper/**"
  - "**/migration/**"
  - "**/*.sql"
alwaysApply: false
---

# Database Rules

Never overwrite raw meteorological data.

Prefer versioned datasets.

Every important dataset should preserve:

- source
- dataset
- version
- processing version

Queries must be bounded.

Avoid unbounded:

SELECT * FROM observations

Large historical queries should use:

- partitioning
- indexes
- asynchronous jobs
- pre-aggregation

Database schema changes require migration scripts.

Never modify production schema manually.

Rule 5：安全

---
description: "气象平台安全规则"
alwaysApply: false
globs:
  - "**/security/**"
  - "**/auth/**"
  - "**/api/**"
  - "**/*.sql"
---

# Security Rules

Never:

- hardcode API keys
- hardcode passwords
- commit credentials
- log access tokens
- expose stack traces
- bypass authorization
- send sensitive data to external AI services

Before introducing an external data source, verify:

- source
- provider
- license
- usage scope
- redistribution
- retention
- security requirements

Public accessibility does not imply authorization for production ingestion.

八、不要把 RETE 写成业务规则

QC 规则必须具备声明式、可配置、可测试、可版本化的特征。

Drools 、RETE 、Java Rule Engine、 Python、 Flink 是属于architecture.md的技术实现，这样更换规则引擎，不需要重写业务规则

九、不要因为 AI 而过早微服务化

weather-platform
│
├── ingestion
├── quality
├── data
├── analytics
├── api
└── ai

先模块化，等团队规模 数据吞吐 故障隔离 部署频率 资源隔离 服务独立扩展这些证明需要拆分，再演化为微服务：架构应该被业务和规模推动，而不是被技术栈推动，不要为了炫技而增加复杂度

十、Skills：

不要只是 Prompt，要成为 SOP

skills是精华提炼，是过去的巨人，他可以这样写：

---
name: qc-rule-writer
description: "创建或修改气象数据质量控制规则"
---

# QC Rule Writer

## Trigger

当用户需要：

- 新增 QC 规则
- 修改 QC 规则
- 分析异常气象数据
- 编写 QC 测试

时使用。

## Workflow

1. Read docs/business-rules.md
2. Read docs/data-contracts.md
3. Inspect existing QC rules
4. Identify affected dataset
5. Identify variable and unit
6. Determine applicable rule type
7. Check existing rules for conflicts
8. Design rule
9. Generate boundary cases
10. Generate abnormal cases
11. Implement
12. Run tests
13. Report changes

## Required Output

必须说明：

- Rule name
- Applicable dataset
- Variable
- Unit
- Conditions
- Action
- Quality flag
- Test cases
- Risk

数据源接入

data-source-onboarding重在流程：以后接入咱就按这套SOP工作

发现数据源
    ↓
确认 Provider
    ↓
确认 License
    ↓
确认使用范围
    ↓
确认更新频率
    ↓
确认数据格式
    ↓
确认 Schema
    ↓
确认时间
    ↓
确认空间
    ↓
确认单位
    ↓
建立 Data Contract
    ↓
建立 Ingestion
    ↓
建立 QC
    ↓
测试
    ↓
进入生产

十一、Sub-Agent：建立真正的专家体系

第一阶段建议 4 个：

agents/
├── qc-auditor.md
├── data-governance-auditor.md
├── security-auditor.md
└── api-compliance-auditor.md

数据治理审查 Agent

---
name: data-governance-auditor
description: "审查气象数据来源、授权、质量、版本和血缘"
readonly: true
---

# Data Governance Auditor

审查：

## Source

- provider
- source
- source reliability

## License

- usage permission
- commercial permission
- redistribution permission

## Provenance

- source
- dataset
- version
- processing

## Data Semantics

- observation vs forecast
- time semantics
- spatial semantics
- units

## Quality

- QC flags
- missing values
- correction history

## AI

- AI-generated data clearly labeled
- external model data flow
- hallucination risk

## Output

按照：

CRITICAL
HIGH
MEDIUM
LOW

输出问题。

每个问题必须说明：

- 文件
- 位置
- 风险
- 原因
- 修改建议

ADR：解决“为什么这么设计”

docs/adr/
├── 0001-timezone.md
├── 0002-raw-data-immutable.md
├── 0003-api-format.md
├── 0004-timeseries-storage.md
└── 0005-ai-data-boundary.md

# ADR-0002 Raw Data Immutable 这样你就告诉了他原始数据是不能修改的

## Status

Accepted

## Context

气象数据需要保留原始来源和历史版本。

直接修改原始数据会破坏：

- 数据血缘
- 审计
- 数据复现
- 数据质量分析

## Decision

Raw meteorological data is immutable.

Corrections must create a new dataset version.

## Consequences

Advantages:

- reproducibility
- auditability
- provenance

Costs:

- additional storage
- version management

测试不能只写在 AGENTS.md

tests/
└── contracts/
    ├── observation-schema-test
    ├── forecast-schema-test
    ├── qc-contract-test
    ├── api-contract-test
    └── provenance-contract-test

把“规则”真正变成系统约束

Database permission
+
Repository architecture
+
Integration test
+
CI check
四层从而形成：
             Rule
              ↓
       Implementation #实施；执行
              ↓
          Test
              ↓
            CI
              ↓
         Production

性能要求必须绑定场景

W1：单站点实时查询
数据：单站点 当前时刻 5～20 个要素
目标： P95 < 200ms 1000 RPS

W2：城市历史查询
数据： 一个城市 24 小时 小时级数据
目标：P95 < 1s

W3：全国历史数据
数据：全国站点 多年历史
目标：异步任务

W4：全国格点数据
数据：大型栅格
目标：对象存储 + 专用数据服务

最终项目结构

weather-platform/
│
├── AGENTS.md
│
├── docs/
│   ├── architecture.md
│   ├── business-rules.md
│   ├── data-contracts.md
│   ├── database.md
│   ├── api-spec.md
│   ├── development-guide.md
│   │
│   └── adr/
│       ├── 0001-timezone.md
│       ├── 0002-raw-data-immutable.md
│       ├── 0003-api-format.md
│       ├── 0004-timeseries-storage.md
│       └── 0005-ai-data-boundary.md
│
├── .ai/
│   ├── coding-rules.md
│   ├── testing-rules.md
│   └── security-rules.md
│
├── .cursor/
│   ├── rules/
│   │   ├── 00-core.mdc
│   │   ├── 10-weather-domain.mdc
│   │   ├── 20-data-quality.mdc
│   │   ├── 30-api.mdc
│   │   ├── 40-database.mdc
│   │   ├── 50-security.mdc
│   │   ├── 60-java.mdc
│   │   ├── 70-frontend.mdc
│   │   └── 80-testing.mdc
│   │
│   ├── skills/
│   │   ├── qc-rule-writer/
│   │   ├── data-source-onboarding/
│   │   ├── api-designer/
│   │   ├── database-migration/
│   │   └── weather-pr-review/
│   │
│   └── agents/
│       ├── qc-auditor.md
│       ├── data-governance-auditor.md
│       ├── security-auditor.md
│       └── api-compliance-auditor.md
│
└── tests/
    └── contracts/

整个体系终态

                    ┌───────────────┐
                    │   AGENTS.md   │
                    │ 项目总入口      │
                    └───────┬───────┘
                            │
          ┌─────────────────┼─────────────────┐
          ↓                 ↓                 ↓
     Business Rules    Architecture      Security
          │                 │                 │
          └─────────────────┼─────────────────┘
                            ↓
                   ┌─────────────────┐
                   │ Data Contracts  │
                   └────────┬────────┘
                            ↓
                   ┌─────────────────┐
                   │     Rules       │
                   └────────┬────────┘
                            ↓
                   ┌─────────────────┐
                   │     Skills      │
                   └────────┬────────┘
                            ↓
                   ┌─────────────────┐
                   │   Sub-Agents    │
                   └────────┬────────┘
                            ↓
                 ┌─────────────────────┐
                 │ Tests / CI / Hooks  │
                 └──────────┬──────────┘
                            ↓
                   ┌─────────────────┐
                   │ Production Code │
                   └─────────────────┘

把气象领域知识、数据治理规则、架构决策、数据契约、开发流程和质量保障体系，全部转化成 AI 可以持续理解和执行的工程资产。