# project-rules

本仓库用于沉淀“项目文档管理与强制规范”，目标是在后续项目迭代中，为 Agent 与开发者提供统一、可执行、可追溯的改动方向约束。

## 核心目标

1. 让程序员能快速看懂模块、业务逻辑、代码实现逻辑，并快速定位相关功能对应文件。
2. 让 AI 能快速理解项目背景、技术栈、文档目录、文档规范、模块与代码文件位置；并在改动后自动更新计划进度、分析结论与报告回归状态。
3. 支持 TypeScript、JavaScript、Java、Python、HTML、CSS 等语言的规范化编写，并为前端、后端应用场景提供可落地的代码规范。
4. 在保证上述能力前提下，遵循按需加载文档原则，降低上下文与 token 成本。

## 目录职责边界（当前约束）

- `developers/`：面向 AI 与人类开发者的协作文档、规范、分析、报告、计划与留痕。
- `docs/`：面向项目软件使用的文档（用户操作、使用说明、产品文档）。
- 面向非开发者或开发者的软件使用文档，在没有特别说明的情况下，Agent 不主动改动。

## 执行原则

- 所有改动需与“核心目标 + 目录职责边界”保持一致。
- 涉及规范、索引、计划、分析、报告变更时，优先保持可追溯与可验证。
- 对文档读取与维护采用最小必要原则，避免无差别全量扫描。

## 推荐入口

- 开发协作总索引：`developers/INDEX.md`
- 软件使用文档索引：`docs/INDEX.md`
- 协作约束入口：`AGENTS.md`
- **接入新项目**：`ONBOARDING.md`