（1523期）Software Engineer – 专业级代码生成规范与架构决策指南

专业级代码生成规范与架构决策指南 面向 AI 编程助手的专业开发规范，提供从代码风格到架构决策的完整最佳实践，帮助在快速交付与工程质量间取得平衡。 使用说明 核心功能与用法 Software Engineer 是一套为 AI 辅助编程场景设计的结构化代码生成规范。它定义了 AI 在编写、审查和重构代码时应遵循的七大核心原则： Read Before Write — 强制要求 AI 先读取现有代码库，匹配既有的风格、命名约定和项目结构 Code That Compiles — 确保代码块包含正确的导入、使用实际存在的 API，杜绝占位符 TODO Minimal First — 反对过早抽象，遵循 "三个具体案例才抽象" 的 YAGNI 原则 Errors as First-Class Citizens — 要求强类型错误、上下文日志、区分可恢复/致命错误 Boundaries and Separation — 明确 Handler/Service/Repository 三层架构的职责边界 Explicit Trade-offs — 架构决策必须记录选择理由、 trade-off 和回访条件 PR-Ready Code — 交付前检查清单：无死代码、函数<30行、无魔数、处理边界情况 显著优点 实用主义导向：区分 "Critical paths"（认证、支付、数据完整性，必须做对）与 "Experimental paths"（UI 特性、分析面板，快速迭代），避免过度工程化 可验证的质量标准：如 "Senior code reads like prose"、"The best code is boring" 等具象化原则，便于自检 架构决策模板化：强制要求用 "选择+理由+trade-off+回访条件" 四元组记录决策，降低技术债务 安全边界清晰：明确声明不存储数据、不发起网络请求、不访问项目外文件 潜在局限性与风险 | 局限/风险 | 说明 ||-----------|------|| 语言/框架中立性 | 规则为通用设计，具体语言的惯用法（如 Rust 的 Result vs Go 的 error）需开发者自行补充 || 静态规范 | 无法自动检测依赖版本变化，"Code That Compiles" 依赖 AI 的知识截止日期 || 主观质量标准 | "30秒让初级工程师理解" 等标准难以量化，依赖个人判断 || 无运行时约束 | 规则为建议性，不阻止 AI 生成违规代码（如无 try-catch 的裸调用） || 本地化缺失 | 全英文规范，非英语团队在术语理解上可能存在偏差 | 适合人群 AI 应用开发者：构建代码生成 Agent 时需要内嵌的系统提示词 技术负责人：为新团队制定代码规范时可直接采用的基准框架 个人开发者：希望提升 AI 辅助编程输出质量的独立工程师 常规风险提示 建议将此 skill 作为 系统提示词（system prompt） 而非用户提示词使用，以确保约束效力 对于高度定制化的代码库（如大量使用内部 DSL），需额外补充领域特定规则 定期回访 "Explicit Trade-offs" 中记录的决策，避免临时方案长期固化 原始说明 Write production-ready code with clean architecture, proper error handling, and pragmatic trade-offs between shipping fast and building right.