The Problem — Context Bloat

痛点——上下文膨胀

How It Works

工作原理

Contract File Example

契约文件示例

# Module: payment
> Payment processing — orders, refunds, billing

## Public API
### Functions
async create_order(amount, currency) → Order
refund(order_id, reason, partial=False) → RefundResult

### Classes
- Order — mark_paid(), cancel()

## Dependencies
- database — order and refund persistence
- gateway  — payment gateway (Stripe, WeChat Pay)

## Side Effects
- [x] Database writes (orders, refunds)
- [x] Network requests (payment gateway API)

## Files
- src/payment/service.py — core payment logic
- src/payment/models.py — Order, RefundResult dataclasses

500 tokens. AI reads this and fully understands the payment module's capabilities — no need to read 300 lines of implementation.

500 tokens。AI 读完这份契约就完全理解支付模块的能力和边界——不需要读 300 行实现代码。

Install & Use

安装 & 使用

$ pip install git+https://github.com/KaiDev-dev/ai-context.git

$ cd your-project
$ ai-context init              # English mode (default)
$ ai-context init --lang zh    # Chinese mode
$ ai-context scan              # Scan code & generate contracts
$ ai-context status            # View token savings report

Generated Project Structure

your-project/
├── .ai/                      # AI context layer (commit to Git)
│   ├── PROJECT.md            # Project overview — AI reads first
│   ├── GUIDE.md              # AI development rules
│   └── contracts/
│       ├── auth.contract.md
│       ├── payment.contract.md
│       └── database.contract.md
├── src/                      # Your code (unchanged)
└── ...

All Commands

所有命令

Configure Your AI Tool

配置你的 AI 工具

Your AI tool needs to know where to find the contracts. Add these rules to your project config.

你的 AI 工具需要知道去哪找契约文件。在规则文件里加上以下内容。

Cursor — .cursorrules

## Context Rules
Always read .ai/PROJECT.md first to understand the project structure.
Before modifying any module, read its contract at .ai/contracts/<module>.contract.md.
Use the Files section in contracts to locate source files — do not scan directories.
After changing a public API, remind the user to run `ai-context scan`.

## 上下文规则
先读 .ai/PROJECT.md 了解项目结构。
修改任何模块前，先读 .ai/contracts/<模块名>.contract.md。
用契约中的 Files 字段定位源文件——不要扫描目录。
修改公开 API 后，提醒用户运行 ai-context scan 更新契约。

Claude Code — CLAUDE.md

## Project Context
- Read .ai/PROJECT.md first for the module map
- Read .ai/contracts/*.contract.md for module APIs before any changes
- Contracts define the interface; source code is the implementation
- After modifying a public API, remind the user to run `ai-context scan`

## 项目上下文
- 先读 .ai/PROJECT.md 了解模块地图
- 改动任何模块前读 .ai/contracts/*.contract.md
- 契约是接口定义，源码是实现细节
- 修改公开 API 后，提醒用户运行 ai-context scan

Windsurf — .windsurfrules

## Context Rules
Read .ai/PROJECT.md first to understand project structure.
Before modifying any module, read the corresponding .contract.md.
Use the Files field to locate source files — don't scan directories.
After changing public APIs, remind user to run ai-context scan.

## 上下文规则
先读 .ai/PROJECT.md 了解项目结构。
修改任何模块前，先读 .ai/contracts/ 下对应的契约文件。
用 Files 字段定位源文件——不要扫描目录。
修改 API 后提醒运行 ai-context scan。

GitHub Copilot — .github/copilot-instructions.md

Read .ai/PROJECT.md first to understand project structure.
Before modifying any module, read the corresponding .contract.md.
Do not scan src/ directory to find files.
After changing public APIs, remind user to run ai-context scan.

先读 .ai/PROJECT.md 了解项目结构。
修改任何模块前，先读 .ai/contracts/ 下对应的契约文件。
禁止扫描 src/ 目录找文件。
修改公开 API 后，提醒用户运行 ai-context scan 更新契约。

Cline — .clinerules

## Context Rules
Read .ai/PROJECT.md first for project map.
Read .ai/contracts/*.contract.md before module changes.
Use Files field to locate source files.
Remind to run ai-context scan after API changes.

## 上下文规则
先读 .ai/PROJECT.md 了解项目结构。
修改任何模块前，先读 .ai/contracts/ 下对应的契约文件。
用 Files 字段定位源文件。
修改 API 后提醒运行 ai-context scan。

💡 Auto-configuration is planned. For now, copy-paste the relevant block above into your tool's rules file.

💡 后期会做自动配置，目前请手动复制粘贴到对应的规则文件。

Real-World Savings

效果实测

On the ai-context project itself (3 Python files):

以 ai-context 自身项目（3 个 Python 文件）为例：

Project: ai-context

PROJECT.md: OK
GUIDE.md:   OK
Contracts:  1

Token comparison:
  Traditional (full scan): ~9,000 tokens
  Contract mode (on demand): ~548 tokens
  Savings: 94%

项目: ai-context

PROJECT.md: OK
GUIDE.md:   OK
契约文件:   1 个

Token 对比:
  传统方式（全量扫描）: ~9,000 tokens
  契约模式（按需读取）: ~548 tokens
  节省: 94%

For a 50-file FastAPI project, estimated savings: 75%-85%.

50 个文件的 FastAPI 项目预计节省 75%-85%。

FAQ

常见问题

Do I need to manually maintain contracts?

需要手动维护契约吗？

No. ai-context scan auto-extracts APIs from your code. Re-run after API changes.

Should I commit contracts to Git?

契约文件应该提交 Git 吗？

Yes. The .ai/ directory should be committed — shared contracts ensure team-wide AI consistency.

应该。.ai/ 目录应纳入版本控制，团队共享才能保证 AI 上下文一致。

How do I switch languages?

怎么切换语言？

Run ai-context init --lang zh for Chinese, or omit --lang for English (default). The setting is saved in .ai/.contractconfig. To change later, edit that file and re-run ai-context scan.

ai-context init --lang zh 中文模式，不加参数默认英文。语言设置保存在 .ai/.contractconfig，后续命令自动读取。要改语言就编辑该文件然后重新 ai-context scan。

What languages are supported?

支持哪些语言？

Currently Python (AST parsing) and TypeScript/JavaScript. Go, Rust, Java planned.

How is this different from .cursorrules?

和 .cursorrules 有什么区别？

.cursorrules tells AI how to write code (conventions, style). Contracts tell AI what the code does (APIs, dependencies, effects). They complement each other.

.cursorrules 告诉 AI 怎么写代码（规范、风格）。契约文件告诉 AI 代码做了什么（API、依赖、副作用）。两者互补，搭配使用。