agentic-cursorrules

赋予你的AI代理空间感。

将大型代码库划分为领域特定的上下文，用于多代理工作流（multi-agent workflows）。此工具生成隔离的markdown规则文件，通过为代理提供明确的文件树边界来防止代理冲突。

存在的原因

我们都遇到过这种情况：你给AI代理访问整个仓库的权限，结果它突然开始"重构"一个实用工具文件，导致五个你甚至没提到的模块失效。

传统工作流会让代理淹没在不需要的上下文中。Agentic-cursorrules 通过将每个代理限制在明确的树状切片中来解决这个问题。对话保持专注，差异保持局部性，协作开销降低，因为你的代理不再试图同时理解整个宇宙。

工作原理

核心来看，这个工具是一个边界管理器。它读取配置文件（可以自动检测！），将目录模式映射到命名的领域。

运行时，它会解析这些领域，遵守你的 .gitignore 规则，并为每个领域生成markdown文件（如 @agent_backend_api.md）。这些文件描述了该特定领域的边界、相关路径和安全准则。你可以在IDE（Cursor、Windsurf等）中引用这些文件，这样你的AI助手就知道自己确切的职责范围——并始终待在这个范围内。

快速开始

你需要 Python 3.10+ 和 uv（因为谁不想快速安装呢？）

# 1. 克隆仓库
git clone https://github.com/s-smits/agentic-cursorrules.git .agentic-cursorrules
cd .agentic-cursorrules

# 2. 安装依赖
uv sync

# 3. 运行设置向导
uv run agentic-cursorrules --init

--init 命令是最友好的启动方式。它会扫描你的项目，推测逻辑领域，并交互式地为你构建 config.yaml。

使用工具

自动模式

只想看看它发现了什么？

uv run agentic-cursorrules --auto-config

这会扫描你的仓库并保存一个 config_auto.yaml 而不会覆盖主配置。非常适合检查你的文件夹结构是否对机器有意义。

手动控制

生产环境中，你可能想在 config.yaml 中手动定义边界：

project_title: "super-app"
tree_focus:
  - "backend/api"       # API团队的领域
  - "frontend/dashboard" # 仪表盘团队的领域
  - "shared/utils"      # 大家最爱的杂物存放处

然后生成文件：

uv run agentic-cursorrules

便捷选项

• --init: 友好的设置向导。
• --verify-config: 干运行（dry-run）显示加载的配置。
• --tree-input: 如果你想从图表生成配置，可以粘贴文本形式的文件树。
• --local-agents: 将生成的markdown文件保留在脚本目录（测试时有用，避免弄乱实际项目）。
• --recurring: 每分钟持续运行（适合活跃的开发会话）。

你将获得的内容

每个领域你会得到一个markdown文件，如 @agent_backend_api.md。

在与AI开始对话时引用这个文件。它包含该领域相关的文件的可视化树状图，以及"仅引用和修改此结构内的文件"的指示。就像给赛马装上眼罩——让它专注向前，快速前进。

仓库结构

让你知道各文件位置：

.agentic-cursorrules/
├── agentic_cursorrules/          # 核心逻辑所在
│   ├── agent_generator.py        # 生成markdown文件
│   ├── config_updater.py         # 管理yaml配置
│   ├── project_tree_generator.py # 绘制树状图
│   └── smart_analyzer.py         # 分析文件夹结构的智能模块
├── main.py                       # 入口文件
├── config.yaml                   # 你的配置
└── pyproject.toml                # 依赖项

agentic-cursorrules 快速上手指南

环境准备

• 系统要求：Python 3.10+
• 前置依赖：uv（推荐使用国内镜像源安装：pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple）

安装步骤

# 1. 克隆项目
git clone https://github.com/s-smits/agentic-cursorrules.git .agentic-cursorrules
cd .agentic-cursorrules

# 2. 安装依赖
uv sync

# 3. 初始化配置
uv run agentic-cursorrules --init

基本使用

最简启动流程

# 自动生成配置文件（推荐首次使用）
uv run agentic-cursorrules --auto-config

手动配置示例

1. 编辑 config.yaml 定义领域边界：

project_title: "super-app"
tree_focus:
  - "backend/api"       
  - "frontend/dashboard" 
  - "shared/utils"      

2. 生成领域规则文件：

uv run agentic-cursorrules

生成的规则文件

• 每个领域会生成类似 @agent_backend_api.md 的文件
• 在 IDE 中引用该文件即可限定 AI 代理的编辑范围