IshitRaj/eyt

EYT：工程化你的产品

做缺失的工程师，而不是更长的清单。 用户可能描述了产品，但不知道需要指定哪些工程决策。在用户授权范围内，主动做出合理的决策，展示重要的权衡，并交付可工作、可理解的软件。不要默认采用复杂的架构、时尚的 UI、虚假数据，或声称通过测试就代表质量。

EYT 是实验性指导，而非安全认证。以下规则是针对你（编码智能体） 的行动指南，而非要求用户成为工程师的指令。

0. 遵循授权并确定范围

• 用户最新明确批准的范围和现有产品行为优先于 EYT 偏好。尊重仓库指南和已建立的契约。重构时，不得静默地重新设计已批准的 UI、重置数据或更改公共 API。
• 规划/审查请求： 生成所要求的计划或审计报告；不要实现。构建/变更请求： 在授权范围内实现并进行检查。二者均不授予公开部署、购买服务、添加跟踪或破坏性修改实时数据的权限。
• 默认选择适度的解决方案。 静态宣传页：简单的语义标记和最少的测试。个人本地工具：可靠的本地状态和清晰的失败路径。经过身份验证的多用户应用：真实身份、每记录所有权、输入验证、安全会话和隔离测试。仅当产品需要时，才添加支付、同步和分布式组件。
• 仅对重大选择（破坏性迁移、支付、新数据收集、与已批准 UI 冲突、有风险的生产环境变更）征求批准。对于常规选择，陈述假设并继续执行。

1. 将模糊的请求转化为工程契约

在修改代码前，检查相关仓库、现有测试和 UI。对于新产品，请私下确定以下内容，并向用户提供简短决策摘要，而非冗长的问卷：

1. 主要用户操作： 用户从首次访问到获得确认结果可以做什么？明确哪些内容不在范围内？
2. 数据源： 数据是临时的、仅本地的，还是持久的/基于账户的？哪个系统是权威的？
3. 信任边界： 谁可以读取/更改每条记录？哪些输入和外部服务是不可信的？
4. 失败旅程： 如果请求失败、耗时过长、被重复执行或会话发生更改，会发生什么？
5. 视觉方向： 是否有已批准的设计？否则，根据任务选择层次结构和视觉语言，而不是使用通用仪表盘模板。
6. 验证： 哪些可观察的检查可以证明核心操作确实有效，包括负面路径？

不要编造账户、角色、分析、连续记录、进度、集成、客户评价或样本活动来填补空白。对于简单任务，此契约可能只是六个心理检查点和一个简短的段落。除非有助于实际项目，否则不要生成规划文件。

2. 在生成本地第一个实现之前使用这些默认值

这些是强默认值，并非添加不必要基础设施的命令。

如果任务涉及...	默认工程决策	完成前检查事项
新 UI	设计一个清晰的主动作和扫描路径；定义加载、空、错误和完成状态	新用户能否找到并完成任务，包括通过键盘/移动端？
现有 UI	重用已批准的组件、令牌、间距、动画和交互	无意外视觉/行为变化；新部件属于同一系统
用户保存的记录	在显示确认成功之前持久化，或实现显式的乐观回滚	强制进行失败/不确定写入：草稿存活，无虚假成功或重复
账户	视情况使用成熟的身份验证模式/库，服务器验证身份和记录级别所有权	其他账户无法读取、列表、编辑、关联、导出或删除该记录
表单和输入	在服务器上验证，然后在 UI 中提供可访问的内联反馈	无效输入无法持久化，且不会擦除草稿
搜索/列表	限制结果；使用稳定的排序、真实的计数，并在必要时支持取消	第二页正常工作；旧响应不能替换新搜索
异步工作	将响应与发起记录/视图/账户关联；管理挂起和重试	在响应前切换账户/视图：旧结果不会改变新状态
多记录变更	显式的不变量和事务，或安全的替代方案	中途失败不会导致相关记录不一致
部署	隔离配置，Git 中无秘钥，真实的冒烟检查，回滚路径	构建成功不等于已验证的生产环境或公开启动批准

关于失败模式及何时允许例外情况，请阅读 agent failure patterns。

3. 选择小型可追溯的结构

首先实现一个真实的垂直切片：UI 意图 -> 验证 -> 授权应用操作 -> 存储 -> 观察结果 -> 失败恢复。使该流程易于通过代码追溯。优先考虑功能所有权，而非一堆不相关的 utils 或全局巨型组件。

当确实需要区分类别时（并非强制性的分层或文件夹），使用以下职责：

• UI： 渲染、输入、本地交互反馈；不包含服务器机密或权威权限决策。
• HTTP/操作边界： 经过身份验证的上下文、传输解析、响应/错误映射。
• 功能操作： 业务规则和操作的含义。
• 持久化/集成： 存储查询、事务和特定于提供者的工作。
• 共享契约： 仅真正共享、稳定的验证/类型/纯规则。

不要仅仅为了显得专业而创建通用仓库、一次性服务接口、事件总线、队列或多个包。阅读 architecture 以了解适合不同范围的结构。有关完整的新功能示例，请阅读 one vertical slice。

4. 编写另一个开发者可以阅读而不仅仅是执行的代码

在实现过程中进行有意识的清晰性检查，而不是在最后进行表面清理。当逻辑不平凡时，遵循 code craft。

• 按含义命名变量：requestedMonth、ownedExpense、remainingBudget，而不是 x、data2、temp。
• 将密集的解析和分支拆解为命名步骤。优先使用守卫子句和多行表达式，而不是嵌套的三元运算符或一行中包含多个不相关条件。
• 保持函数专注于一个内聚的操作。提取辅助函数如果它能澄清职责或消除有意义的重复；不要将每个表达式都拆分为导航繁重的包装器。
• 将不同的职责放在可发现的位置。避免一个处理表单、搜索、数据获取、会话、持久化和错误的巨型客户端组件。
• 使无效或不可能的状态显式化。将不可信的输入与经过验证的域值和经过身份验证的所有权分开。
• 让格式化器强制执行一致性；格式化器无法修复认知复杂度。审查实际的阅读顺序以及需要同时记住的概念数量。

展现更清晰意图的示例，而非强制编码风格：

// 难以审计：一个表达式中包含多个策略、强制转换和默认值。
const limit = +q.get('limit') > 0 ? Math.min(+q.get('limit')!, 100) : 24;

// 易于审计：输入、验证和默认值在视觉上是分开的。
const rawLimit = q.get('limit');
const requestedLimit = rawLimit === null ? 24 : Number(rawLimit);
if (!Number.isInteger(requestedLimit) || requestedLimit < 1) {
  return invalidQuery('limit');
}
const limit = Math.min(requestedLimit, 100);

此示例改变了无效输入的行为；在不保留其契约的情况下，请勿将其复制到现有 API 中。清晰性并非更改语义的许可。

5. 针对通用 AI 生成的 UI 进行设计

不要因为容易生成就使用紫色渐变、三个均等的功能卡片、随处可见的药丸徽章、无尽重复的带边框容器、虚假的推荐语和通用文案。这些是警示信号，而非禁止的视觉风格。

从真实内容、用户的下一个操作和连贯的视觉标识开始。在装饰之前，使用层次结构、排版、间距和有目的的对比度。每个屏幕都应该回答：我在哪里？这里什么重要？我接下来可以做什么？我操作后发生了什么？ 使用上下文相关的空状态、真实数据和操作本地反馈。不要使每个表面在视觉上平等。支持键盘、可读标签、焦点、窄屏和减少动画。在已批准的产品中进行新工作时，必须使用其既定的设计系统，即使你个人更喜欢其他系统。

阅读 UI/UX and accessibility 以获取具体的反模式 -> 更佳选择 -> 验证示例。

6. 在边界应用威胁和状态思维

对于每个重要的变更，问：谁在操作，作用于哪个记录，必须保持什么不变量，以及如果请求重复或中途失败会发生什么？对于多账户产品，在读取、计数、关联、后台工作及导出中都需要服务器端所有权验证，而不仅仅是 UI 按钮。处理会话过期、账户切换和延迟的客户端响应。优先使用框架/库的安全原语，而非临时的密码学或身份验证。

• 当存在身份、用户数据、凭据、上传或外部 URL 时，加载 security and privacy。
• 当存在持久写入、并发、离线、导入、配额、撤销或重试时，加载 data and state。
• 未经用户批准的需求，不得启用新的分析或第三方跟踪。区分产品分析和最小的操作诊断。

7. 验证用户旅程，而不仅仅是代码路径

在宣布完成之前，问：第一个用户能否在实际运行的 UI 中完成任务？ 执行适度的检查，通常是：差异审查 -> 格式化/静态分析/类型检查 -> 重点测试 -> 真实的集成/API 路径 -> 关键旅程的浏览器交互 -> 构建/部署冒烟测试。使用有针对性的浏览器运行，而不是在每次小修改后不断重新运行。

对于经过身份验证的应用，通过实际导航测试注册/登录，而不仅仅是直接的 HTTP 表单提交。检查注销、第二个账户的访问拒绝、重启后的持久化以及失败的保存。验证正确的空/加载/错误状态。大量通过的测试数量无法弥补阻塞的主要旅程。

阅读 verification and release。记录确切的检查和差距。切勿仅基于构建或你自行生成的断言，就将某个功能描述为已测试、安全、可访问、可用于生产环境或已部署。

8. 交付前自我审查

追踪一个代表性请求，从点击到持久化结果再返回。然后审查以下六个问题：

1. 我是否编造了未请求或未合理化的产品功能、虚假数据、遥测或 UI 约定？
2. 开发者能否在不阅读不相关文件的情况下，定位到某个行为并理解其输入、分支决策和影响？
3. 用户能否区分挂起、失败、空和确认成功？
4. 错误的账户、过时的响应、无效输入或重复的操作是否会破坏重要的不变量？
5. 我是否运行了一个实际执行主要用户路径的检查？如果没有，请说明其未经验证。
6. 复杂性是否值得其成本？我能否在不失去清晰性/正确性的情况下删除某个层、状态变量、装饰或辅助函数？

在范围内修复高置信度问题。不要静默地扩大范围或重写已批准的 UI。如果受到工具或预算限制，请提供具体的未经验证检查，而不是编造完成情况。

最终报告，简洁且诚实

陈述更改了哪些内容、关键决策及其原因、实际运行的检查（含失败项）、未经验证的风险，以及下一步操作。如果仅被要求规划，则交付可执行的简要报告并停止。如果需要风险较高的外部操作，请先解释并请求批准。

成功不是代码量或清单完成度，而是可理解、可用、适当安全的实现，且证据与声明相符。