# 知了项目级开发约束

本文件是仓库级协作入口。进入本仓库后，应先读取本文件，再按任务范围读取对应规范和领域文档。

## 语言与文件

- 默认使用简体中文沟通、写文档、提交说明和任务说明。
- 源码与文档保持 UTF-8、LF；代码注释使用简体中文，并优先使用 GB2312 常用字符。
- 专有名词、命令、API、变量、类型和文件名保留英文。

## 必读顺序

1. [README.md](README.md) 的 Roadmap 与新功能冻结规则。
2. [CONTEXT.md](CONTEXT.md) 的领域术语和产品不变量。
3. 与任务相关的 [ADR](docs/adr/)。
4. [产品规划交付包](docs/产品规划/README.md) 和当前 Issue 执行计划。
5. [开发规范](docs/开发规范.md)；涉及页面或交互时同时读取 [UI 规范](docs/UI规范.md)。

发生冲突时，不得静默选择。先按上述优先级核对事实，再在任务说明中写明冲突、采用结论和原因；架构决策发生变化时补充 ADR。

## 产品边界

- 知了是单用户、自托管、主题导向的个人知识库，不建设注册、多用户、RBAC、SaaS、工作流画布、知识图谱或白板。
- 真实笔记达到 100 条前冻结新功能。缺陷、文档、分发、部署和运维可以继续。
- 新页面、新数据表、新持久化状态、新内容类型和新一级导航默认视为新功能，必须有明确批准或冻结例外。
- AI 负责整理与取用，不得覆盖用户正文；来源问答必须受来源集约束，资料不足时明确拒答。
- SQLite 是工作库，Markdown、图片、备份和恢复共同构成用户的数据出口。

## 开发流程

- 默认先调查现状，再说明当前理解、计划、影响范围、风险和验收标准。
- 中等及以上复杂改动在获得确认前不得进入实现。
- 多 Agent 默认关闭，未经用户明确同意不得开启。
- 修改应紧贴现有模块边界，避免无关重构、依赖升级和元数据变更。
- 涉及接口、数据库、流程、配置、部署或页面行为时，必须同步更新相关文档。

## 验证

- 先执行与改动范围匹配的局部验证，复用已有证据，不重复运行同类重验证。
- `build`、全量测试和重型浏览器验证默认先说明必要性，获得确认后再运行。
- 正式合并或发布前的完整门禁仍为：`npm run check:design`、`npm run lint`、`npm test`、`npm run build`。