Imported from 114August514/engineering-workflow (templates/project-skeleton/AGENTS.md). Install upstream with npx skills add 114August514/engineering-workflow --skill project-skeleton. Copyright stays with the author.

{{PROJECT_NAME}}

{{一句话说这是什么}}

这是宪法：只放不会过期的约束和指针。 展开的做法在 docs/conventions.md——动手前读它。

验证

提交前必须跑：

make check

它包含格式检查、lint、类型检查、测试。不要另外发明命令， 不要直接调用底层工具——make check 是唯一的真理。 声称"做完了"之前跑它，并把输出贴出来。

make journal 看在途工作 · make audit 出待审清单 · make doctor 体检基线。

目录

• src/<上下文>/ —— 按限界上下文分，不按技术层分
• src/*/domain/ —— 纯业务规则，不许 import 任何 IO（数据库、HTTP、文件、时钟、随机数）
• src/*/app/ —— 用例编排，事务边界在这一层
• src/*/infra/ —— 数据库、外部调用
• contracts/、migrations/ —— 🔴 改动前必须先问人

文档：docs/spec.md 验收标准 · docs/glossary.md 术语与不变量 · docs/decisions/ 为什么这么设计 · docs/runbook.md 部署与回滚 · docs/journal/ 在途工作 · docs/conventions.md 怎么干活

命名

所有概念用 docs/glossary.md 里的名字。代码标识符、数据库列、接口字段、 日志字段全用同一个词。需要新概念时先往术语表加一行再写代码。

不变量

不能违反 docs/glossary.md 里的 INV-* 条目。数据库约束是最后一道防线， 不要因为应用层已经校验过就省掉它。

禁止

• 不许改 contracts/、migrations/、认证授权相关代码 —— 先提出来让人决定
• 不许新增依赖 —— 先按 docs/conventions.md 的四层检索走一遍
• 不许手搓安全 / 时区 / 协议解析 / 金额精度 / 重试退避
• 不许 skip / 注释掉 / 放宽失败的测试。测试红了就是代码错了
• 不许写只调用不断言的测试，或 mock 掉一切然后断言 mock 被调用了
• 不许在错误里用临时字符串，错误码登记在 contracts/errors.md
• 不许硬编码配置（URL、密钥、路径），从环境变量读
• 不许过度设计：只有一个实现就不要抽接口，没人用的配置项就是常量
• 不许为想象中的故障写防御 —— 没发生过的写进风险记录，不写进代码
• 产生仓外副作用前没写下撤销方式 —— 停下来问人

三条顺序不能反

1. 先搜再写 —— 仓库里已经有了吗？标准库有吗？已装的依赖有吗？
2. 先写测试再写实现，而且要亲眼看到它红
3. 先写意图再动手 —— ./scripts/journal.sh --new <slug> <上下文>， 会话会死，写完意图那一刻才是可恢复的

汇报

完成时说清六件事：做了什么 / 没做什么 / 怎么验证的（贴输出）/ 哪里不确定 / 故意没处理的 / 碰了哪些文件。

不要用"应该没问题""看起来是对的"收尾。要么验证过并给出证据，要么明说没验证。