夜雨聆风HI，我是不会编程也不会 UI 的小美工金洲大叔～～
每次我在新建项目的时候总感觉需要一个最底层的思路来支撑本次的 AI 编程任务，之前使用 Claude oups 4.6的时候，我一直都是一遍做一遍让它总结本次任务的问题或者根据本次会话拟定一些规范和一些边界，比如做了一个接口后，前端字段和后端字段不一致，导致出现错误；或者是数据库没有这个字段。。。或者 UI 和整体风格不一致的问题。
之前使用 Claude oups 4.6的时候，我一直都是一遍做一遍让它总结本次任务的问题或者根据本次会话拟定一些规范和一些边界，比如做了一个接口后，前端字段和后端字段不一致，导致出现错误；或者是数据库没有这个字段。。。或者 UI 和整体风格不一致的问题。
也就是搞一个项目，基本每次的规范文件之类的都是不一样的东西。
无法沉淀啊～
我想是因为我是保安（有证！）出身，对软件工程并不了解的原因。
所以我一直在想有没有方法可以“0帧起手”～～～真正的做到要他做啥就做啥。
不需要再去考虑一些不懂的问题。
所以，让 GPT5.5做了一份这玩意～
文章有点长～如果不想读完，就直接让元宝总结。
AGENTS.software-project.template.md 是一份给 AI 编程助手使用的项目协作规范模板。
它不是普通 README，也不是需求文档。它的作用是：在一个新项目开始前，先把技术栈、业务边界、开发约束、UI 规范、后端规则、验证标准写清楚，让 AI 在后续开发时少猜、少乱改、少过度设计，并且每次改动都能围绕可验证目标执行。
这份模板的工程行为内核，基于 forrestchang/andrej-karpathy-skills 的思路继续扩展。原项目把 Andrej Karpathy 对 LLM 编码问题的观察整理成一个单文件规范，核心是四个原则：编码前思考、简洁优先、精准修改、目标驱动执行。
本模板在此基础上，继续加入了项目事实、技术栈、Web/iOS/Android/鸿蒙/单机/后端服务规范、业务状态机、权限边界和验证清单，让它更适合作为不同软件项目的 AGENTS.md 起点。
这份模板适用于：
Web 前端项目、iOS 原生项目、Android 原生项目、鸿蒙项目、Flutter、React Native、UniApp 等跨端项目、桌面端项目、单机离线应用、后端服务、前后端全栈项目。
它的核心目标不是限制开发，而是让开发更稳定：先明确项目事实，再执行具体任务。
文件获取请留言～
AGENTS.software-project.template.md文档介绍
AI 写代码时常见的问题有四类。
第一类是错误假设。
需求不清楚时，AI 可能会自己选一种解释，然后直接写代码。模板里的“编码前思考”要求它先暴露假设、说明权衡，关键规则不清楚时停下来问。
第二类是过度复杂。
很多简单需求会被写成一套过大的抽象、配置和兼容层。模板里的“简洁优先”要求只解决当前问题，不提前设计不存在的未来。
第三类是改动失控。
AI 有时会顺手重构旁边代码、格式化无关文件、删除它认为没用的东西。模板里的“精准修改”要求每一行修改都能追溯到用户请求。
第四类是缺少验证。
代码看起来改了，但没有明确怎么证明完成。模板里的“目标驱动执行”要求每个任务都有成功标准和验证路径。
这四条原则是整份模板的基础，后面的 Web、移动端、后端、单机规则都建立在这四条之上。
模板从上到下分成几个层级。
这里记录模板版本、来源项目、适用项目、项目类型和当前阶段。
新项目复制后，先改这一段。例如：
- Template Version：`0.1.0`- 来源沉淀：`某个已完成项目 / 2026-04`- 适用项目：`某某业务系统` - 项目类型：`Android / 后端服务 / 全栈`- 当前阶段：`MVP`
这是最重要的部分，建议所有项目都保留。
这部分告诉 AI：先想清楚，再动代码；能简单就简单；只改该改的；最后必须验证。
如果一个项目时间紧，也不要删这部分。
它是防止 AI 失控的底线。“0”帧起手的重要核心。
这里填写项目的基本情况。
包括：项目名称、业务目标、核心用户、核心业务对象、核心流程、技术栈、端口与环境等
这部分的作用是让 AI 不再反复猜项目类型。
例如你明确写了“后端端口 8080”，它后续就不应该默认使用其他端口。
移动端项目也一样。你明确写了 Android 用 Kotlin + Jetpack Compose + Room，AI 就不应该突然引入 Flutter 或 SQLite 裸操作。
这里规定 AI 修改代码前应该先读哪些文档。
典型顺序是：
1. 产品/开发方案2. 业务需求文档3. 流程/状态机文档4. 接口文档5. 数据模型文档6. UI/设计规范7. 测试/联调账号/验收文档8. 部署/运维文档
真实项目里，需求文档、接口文档、代码实现经常不一致。
模板里规定了冲突处理原则：已落地实现和真实数据优先，涉及权限、资金、隐私、删除、状态流转时必须先澄清。
可以，而且建议引入。
但链接的作用应该是“指路”，不是替代规则本身。
外部链接适合放：官方文档、技术栈规范、第三方库说明、设计系统入口、方法论来源等
例如：- 行为规范来源：[andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)- Vue 官方文档：[Vue Docs](https://vuejs.org/)- NestJS 官方文档：[NestJS Docs](https://docs.nestjs.com/)
项目内文件链接适合放：需求文档、开发方案、UI 规范、接口文档、数据库设计、测试账号和验收说明、具体业务边界文档
例如：
- 产品方案：[开发方案.md](./开发方案.md)- 业务需求：[业务需求文档.md](./业务需求文档.md)- UI 规范：[UI 规范.md](./UI规范.md)- 后端说明：[backend/README.md](./backend/README.md)- 权限边界：[docs/permissions.md](./docs/permissions.md)
关键规则要写进 AGENTS.md 或本地文档，不要只丢一个外链。
外链可能变动、失效、需要登录或无法联网访问，所以不能作为唯一依据。
模板文件里尽量用相对路径；
具体项目里如果工具支持，也可以用绝对路径方便点击。
不应该每次都读，也通常不会自动全部读！
正确做法是：AGENTS.md 本体先提供足够的核心规则，链接只作为“按任务触发读取”的补充材料。
你可以在模板里写清楚触发条件，让 AI 知道什么时候必须读哪个文档。
推荐写法：
文档读取触发规则 不要默认一次性读取所有链接。按任务类型读取：- 改业务流程、状态机、审批/任务流转：先读开发方案.md、流程文档.md- 改接口、字段、鉴权、错误码：先读backend/README.md、接口定义和类型文件- 改 UI、布局、交互、文案：先读UI 规范.md- 改权限、列表、详情、按钮显隐：先读权限边界文档.md- 改数据库 schema、迁移、种子数据：先读schema.prisma、迁移说明- 改部署、端口、环境变量、安全头：先读部署文档.md、.env.example外部链接只在以下情况打开：- 本地文档明确要求参考- 用户要求确认最新官方行为- 当前实现与本地文档冲突，需要查官方文档- 涉及第三方 API、SDK、平台规则，且版本可能变化
这样可以控制 AI 的阅读范围。
好处是：
小任务不会浪费上下文读取一堆无关文档。
高风险任务会强制读取必要文档。
外部链接不会变成唯一依据。
AI 更容易说明“我为什么读了这些文件”。
一个实际例子：
如果你让 AI “修一下登录 404”，它应该读端口/API 基址/后端路由相关文档，而不是去读全部 UI 规范和所有业务流程。
如果你让 AI “修改业务单据审批按钮权限”，它必须读权限边界文档和当前后端对象级权限实现，而不是只改前端按钮显隐。
这部分是所有项目都应该遵守的工作边界。
它告诉 AI：
不要引入未要求的 mock 回退不要改用户已有变更不要做无关重构不要擅自改端口、鉴权、安全头、迁移策略新增接口或字段时，要同步检查客户端 API、类型定义、页面状态和文档
这部分适合直接复制到具体项目的 AGENTS.md。
模板里新增了一章“软件安全基线”。它是默认安全底线，面向多个技术栈，不只服务后端。
如果项目安全要求更高，则继续往里面补充。
它覆盖六类内容。
通用安全原则：密钥、token、数据库连接、客户数据不能写进代码、日志、模板或公开文档。所有外部输入都不可信，前端表单、移动端请求、本地文件、导入数据、第三方回调都要校验。权限必须由后端或可信本地权限层强校验，UI 隐藏按钮不能等于安全。账号、API token、数据库账号、云资源权限都要最小化。登录、权限变更、删除、导出、支付、同步等关键动作要留痕。Web 安全：避免 XSS，不直接渲染不可信 HTML。Cookie 鉴权要考虑 CSRF。CORS 不能在生产环境无脑放开。CSP、iframe、文件预览、安全头要同时兼顾安全和业务可用性。下载、导出、附件预览必须鉴权、限流、审计。移动端安全：iOS、Android、鸿蒙都不能把敏感数据明文放普通本地存储。token 优先用 Keychain、Keystore 或系统安全存储。网络请求必须使用 HTTPS，不要为了调试长期关闭证书校验。日志和崩溃上报不能输出 token、手机号、身份证、地址等敏感字段。App 可被反编译，所以核心鉴权和越权控制必须放到服务端或可信环境。单机与离线安全：本地文件导入要防畸形文件、路径穿越、超大文件和异常编码。本地数据库要考虑迁移、备份、恢复和异常退出一致性。同步冲突不能导致越权覆盖或数据污染。导出文件可能含敏感信息时，要提示用户并控制范围。后端服务安全：鉴权、RBAC、对象级权限、租户隔离必须在后端强制执行。状态机和关键业务动作不能只靠前端控制。ORM 查询也要防越权查询。文件上传要校验大小、MIME、扩展名、数量和对象归属。下载、预览、导出要用短效授权或签名 URL，并记录审计。AI 协作安全规则：AI 不得把真实密钥、账号密码、数据库连接、客户隐私写进回答或文件。AI 不得为了方便调试长期关闭鉴权、CORS、TLS、证书校验、安全头。AI 不得随便引入低质量依赖。改登录、鉴权、权限、支付、导出、删除、同步、部署安全配置时，必须先说明风险和验证计划。
这章的价值是：即使下个项目不是 Web 后台，而是 iOS、Android、鸿蒙或单机应用，也有一套基础安全检查框架。
前端与客户端工程规范
这一章不再只按平台罗列注意事项，而是把 Web、iOS、Android、鸿蒙、跨端、桌面端、单机离线统一放在“客户端工程”视角下。
它关注七类通用问题。
架构与分层：- UI 层只负责展示、交互和局部状态。- 网络访问、错误映射、鉴权续期、环境切换要集中封装。- 相机、定位、文件、推送、蓝牙、系统分享等平台能力要通过适配层调用。- 公共组件只在真实复用出现后抽取。状态管理与数据流：- 区分服务端状态、本地状态、UI 临时状态。- 服务端状态要有加载、成功、空数据、错误、过期、刷新中表现。- 表单编辑要有初始值、脏状态、保存中、提交中、失败恢复和离开确认。- 跨页面共享状态要定义失效时机。网络与接口：- API/SDK 层统一处理 baseURL、鉴权头、token 刷新、超时、取消、重试、错误消息。- 创建、支付、审批、删除、同步等动作不能盲目重试。- 弱网、断网、超时、401、403、409、422、500 等状态要有可理解反馈。- 客户端类型定义要和接口契约同步。UI、交互与可访问性：- 优先使用项目指定组件库或设计系统。- 布局、间距、按钮层级、表单校验、弹窗确认、空状态、错误状态保持一致。- 危险操作必须二次确认。- 权限按钮显隐只做体验优化，最终权限由后端或可信权限层校验。- 要考虑键盘可达、焦点状态、屏幕阅读器语义、颜色对比、动态字体或系统字号。表单、文件与本地数据：- 表单字段改动必须验证新建、编辑回显、再次提交、旧数据兼容和空值处理。- 日期、金额、数字、时区、枚举、多选、动态列表、富文本要有统一格式化和解析规则。- 文件上传、下载、预览、导入、导出要校验类型、大小、数量、权限和失败恢复。- 本地缓存和本地数据库要有版本、迁移、清理、备份或恢复策略。- 性能与可靠性： 首屏、列表滚动、图片/文件预览、大表单、大数据量场景要避免明显卡顿。- 长列表、媒体资源、地图、图表、大文件应按需加载、分页、虚拟化或压缩。- 关键异步流程要处理取消、重入、重复点击、后台恢复、页面销毁后的回调。- 错误边界或兜底页面要阻止局部异常拖垮整个应用。平台专项：- Web 关注路由守卫、CORS、CSP、iframe、安全头和文件预览。- iOS 关注生命周期、安全区、动态字体、深色模式、后台任务、权限拒绝和 Keychain。- Android 关注生命周期、旋转、进程重建、运行时权限、后台限制和数据 migration。- 鸿蒙关注 Ability 生命周期、ArkUI 状态更新、 module.json5 权限、Preferences/relationalStore 和真机差异。- 跨端关注平台差异集中适配。- 单机/离线关注无网可用范围、本地数据一致性、导入导出、同步冲突和异常退出恢复。
新项目可以删除无关平台小节，但不建议删除“架构、状态、网络、数据、体验、验证”这些横切规则。
把文件复制到新项目根目录，建议命名为：AGENTS.md如果你想保留原始模板，也可以同时保留：AGENTS.software-project.template.md AGENTS.md（或者你改个 REDME.md也可以，你喜欢就好）
搜索所有 {{...}}。逐项替换成新项目的真实信息。至少要替换：{{项目名称}}{{项目类型}}{{技术栈}}{{核心业务对象}}{{核心流程}}{{前端端口}}{{后端端口}}{{API_BASE_ENV_NAME}}{{默认 API 地址}}{{常用命令}}如果某一项不适用，直接删掉，不要保留空占位符。
第三步：删掉无关平台
如果项目只是 Web + 后端，就删掉 iOS、Android、鸿蒙、桌面端段落。
如果项目只是 Android 单机应用，就删掉 Web、后端服务中不相关的部分，保留 Android 和单机离线章节。
模板不是越全越好。
具体项目里的 AGENTS.md 应该短、准、可执行。
重点补这几块：角色权限表核心状态机列表/详情/编辑/处理边界删除、撤回、退回、重提、归档规则文件、导出、本地数据、同步规则
这些规则越清楚，AI 后续改代码越稳。
不懂的话，也让 AI 补，补了之后你再看一遍。
把项目真实命令写进去。
例如 Web 全栈项目：cd backend && npm run lint && npm run build cd frontend && npm run build
例如 Android 项目：./gradlew test ./gradlew assembleDebug
例如鸿蒙项目：{{DevEco 构建方式或 hvigor 命令}}
能自动化的验证尽量写命令，不能自动化的验证写清楚人工检查步骤。
对，不懂还是让 AI 补～
每个项目结束后，从实际项目的 AGENTS.md 里让AI挑出通用经验，合并回 AGENTS.software-project.template.md。
不要把项目专属业务硬塞回通用模板。只沉淀能复用的规则。
这一句你做完一个大功能后，可以让 AI 看着总结进去
适合沉淀：新平台的权限/构建/验证规则常见事故的预防规则通用 UI/后端/客户端边界可复用的测试标准
不适合沉淀：某个客户的账号密码某个项目的私有接口某个临时绕过方案一次性部署路径
最推荐的方式是保留两层文件。
第一层是通用模板：AGENTS.software-project.template.md它负责长期进化，不直接服务某个项目。
第二层是项目实例：AGENTS.md它从模板复制而来，只保留当前项目真正需要的规则。
这样不会让单个项目的 AGENTS.md 过度膨胀，也不会让通用模板被项目细节污染。
记住 AGENTS.md不是越详细越好的！！！
别限制了 AGENT 的发挥！！
我们只做引导、边界、资料等！！
以上这套也适合使用到培养小孩身上～～
一句话使用原则先用模板建立项目边界，再让 AI 写代码。如果边界不清楚，AI 会猜；如果验证不清楚，AI 会停在“看起来完成”；如果规则不进化，每个项目都会重复踩坑。
你就下载这个 md 文件，给到你的 AI 对他说：
这是我给这个项目准备的 AI 协作开发规范。请你先完整阅读它，理解里面的工程执行原则、项目事实、技术栈、业务边界、权限规则和验证标准。以后在这个项目里写代码、改代码、排查问题、做 UI、写后端、改移动端或做单机功能时，都要优先遵守这份规范。如果你发现规范里有不清楚、冲突或不适合当前项目的地方，先告诉我，不要自己猜。如果你认为规范需要补充，请给我一版修改建议。
文件获取，请留言～
