tech-preferences

技术偏好

将这些默认选项用于 James 的个人软件项目。本技能关注使用什么来构建；engineering-principles 关注如何设计，verifiable-trust 关注 AI 验证和执行风险。

如何应用

1. 首先检查仓库状态、相关的 AGENTS.md 说明和已记录的决策。现有技术是参考依据，但不一定代表永久的架构决策。
2. 对于新工作，遵循以下默认选项。在现有项目中，尽早指出有实质影响的偏离，并在适当时建议保持一致；说明权衡，并在迁移前征求同意。绝不要顺带进行迁移。
3. 如果 James 选择保留某项偏离，就在适当的仓库文档中记录该决定及其理由。除非对方提出要求，或有实质性的新证据值得重新考虑，否则不要再次提出。
4. 如果现代替代方案能带来实质性改进或学习机会，就主动提出，并明确区分成熟技术与实验性技术，同时说明风险、运维成本和可逆性。引入任何不熟悉的技术前都要征求同意。 避免昙花一现的潮流技术。
5. “探索”代表感兴趣，不代表批准采用。已记录的项目决策和明确排除项优先于通用偏好。优先复用现有惯例和基础设施。

语言和前端

分类	指引
优先选择	新后端、命令行工具和开发者工具使用 Go。优先使用 Go 标准库；有需要时采用小型、专注的库。
Go 命令行工具	无需交互的可执行程序和简单命令优先使用标准库参数解析。对于采用结构化命令树、标志、帮助或补全功能能带来益处的、面向用户的命令行工具，使用 Cobra；使用 cobra-cli 搭建该命令行工具。只有在配置复杂度足以值得采用时才添加 Viper。
优先选择	前端使用 React + TypeScript + Vite，包管理器使用 npm，并采用 ESLint 和 Prettier。共享状态使用 Zustand。
可接受	Tailwind CSS；组件、路由、查询、表单和验证库按具体情况选择。不强制指定设计系统。
强烈避免	除非有极其充分且具体的理由，否则不要使用 Next.js，优先选择 React + Vite。引入前须征求同意。
避免	除非有明确要求，否则不要使用 Redux、Java、C#/.NET、PHP 和重量级企业框架。
脚本	使用 Just 作为任务运行器。Bash 只用于少量开发辅助工作；不要编写大型 Bash 脚本。可复用工具使用 Go。Python 主要用于机器学习，而非通用脚本。
探索	可探索微前端和 Module Federation，但不作为默认选项。
质量	UI 应具备响应式设计和无障碍特性，并与项目成熟度相称。

Go CLI 惯例

• 根据命令契约选择，而非可执行文件的数量。 Kubernetes 初始化进程、守护进程或简单的单命令工具通常只需要标准库 flag（或不需要解析器）。不要为了使用而引入 Cobra、Viper、生成的命令包或补全代码。
• 当维护中的交互式／面向用户的 CLI 有足够多的命令、标志行为、补全或帮助需求，能从中获得实质性益处时，使用 Cobra。对于新的 Cobra 命令，在现有模块内使用 cobra-cli init/add 搭建框架；让命令文件专注于解析和分派，并将行为放在职责明确的 internal/<capability> 包中。
• 对于现有 CLI，在选择解析器或迁移之前，先检查实际调用方和行为。保留有文档说明的标志、位置参数、stdin、信号和退出状态；生成到临时位置，而不是覆盖现有文件。
• 只有在确实需要从多个来源加载配置时才使用 Viper。对于少量设置，优先使用普通环境变量或简单标志。
• 优先采用符合 Go 惯例且明确的代码，而不是巧妙或一刀切的风格转换。可将 Go 代码审查建议 和 Google Go 风格指南 作为实用参考；外部技能和任意的数值风格阈值都不能凌驾于可读性或有文档记录的项目决策之上。

应用、接口和数据

• 代码库和部署结构： 每个副项目、产品或自包含概念使用一个单体代码库。优先将不同的后端领域拆分为小型、可独立部署的微服务，即使是小型项目也如此。不要将前端和后端合并为一个单体应用。可独立部署并不意味着要使用不同的代码库或基础设施栈。
• API： 默认使用 gRPC + Protobuf，并为浏览器或外部客户端提供 REST/JSON 网关。欢迎使用 Buf 和 gRPC 库／框架。默认从 REST 网关的 OpenAPI 契约生成前端 TypeScript API 客户端。Protobuf 生成的客户端不必意味着浏览器直接使用 gRPC，但 OpenAPI 符合这种首选的浏览器集成方式。基于 gRPC 的 GraphQL 仅适合经过审慎考虑后再探索。
• 数据库： 默认使用 PostgreSQL。对于确实很小或嵌入式的场景，使用 SQLite；熟悉 MongoDB，在适用时也可以接受。GORM 是熟悉的选择；sqlc 是值得评估的有趣替代方案，但并非强制默认选择。避免使用存储过程。
• 通信： 对即时一致性需求使用同步流程；对于有意采用的最终一致性，使用异步流程。在合适的情况下，优先采用事实／事件驱动集成，而非命令式消息传递。在有所帮助时使用 Dapr 的发布／订阅、服务调用及相关能力，但不要引入不必要的间接层。
• 身份： 使用托管 OIDC/OAuth，而非自行实现身份验证。Auth0 是熟悉的选择；在获得许可后可探索 Stytch。明确处理授权。

基础设施、运维与安全

• 托管： 仅使用现有的 Rackspace Spot Kubernetes。即使是小型项目也使用 Kubernetes；未经批准，不要引入新的云或托管平台。
• GitOps： 第一方服务使用 Argo CD + Kustomize；第三方应用使用 Helm。避免使用 Terraform。沿用当前基础设施和部署惯例。
• 开发： 使用 Devcontainers、Just 和 Docker/Compose；确保工具可复现，并记录本地设置步骤。
• CI/CD： 使用 GitHub Actions，并将构建、发布和部署/晋级工作流分开。沿用现有流程。只构建一次，为不可变产物指定版本，并晋级同一产物。使用多阶段精简容器镜像、固定基础镜像、非 root 运行时和不可变镜像标签。
• 配置： 使用环境变量配置特定环境的设置，使用 Kubernetes Secrets 管理凭据，仅在需要时采用合适的其他密钥管理方案。可审核的应用策略可纳入版本控制的结构化配置；绝不嵌入密钥。
• 遥测： 使用 OpenTelemetry 插桩、结构化日志、指标和分布式追踪；采用包含 Prometheus、Loki 和 Tempo 的 Grafana 生态系统。
• 弹性： 明确处理错误，设置合理的超时和有界重试，配置 Kubernetes 健康检查/就绪探针、优雅关闭和资源限制。在 Dapr 能减少自定义连接代码时使用它。只有在确有必要时才添加高级弹性模式。
• 安全： 即使在实验项目中也默认采用安全配置：遵循最小权限原则、限制权限、使用非 root 容器、验证输入，并进行安全与依赖项扫描。

验证、依赖项与文档

• 行为实现和缺陷修复默认采用 TDD。 遵循 Matt Pocock 的 implement → tdd 工作流：先就实用的公共测试切入点达成一致；在实现之前编写一个失败的行为测试（红）；只实现足以通过测试的内容（绿）；然后以小型垂直切片重复此过程。测试外部可观察到的成功、失败和恢复行为；预期结果应独立推导，而不是仅仅复述代码。对于非行为性工作或难以实际测试的工作，应明确说明例外理由，而不要编写价值低的测试。
• Go 集成测试使用 testing 包 + Testcontainers。前端使用 Vitest + React Testing Library + Playwright。
• 在 CI 中强制执行格式化、代码检查、类型检查和安全扫描；检查应验证真正的不变量。
• 使用精简的依赖项；积极采用真正有用的改进，不要为了回避新工具而拒绝它们。自动更新 minor/patch 版本；major 升级需要批准。无论版本如何，不熟悉的依赖项也需要批准。
• 维护简明的 README、架构和运维文档，提供清晰的构建/测试命令，并为重要且不明显的决策编写 ADR。

推荐技术时，应明确指出默认方案、重大偏离、权衡取舍、需要明确批准的事项，以及值得记录的决策。避免反复讨论已经确定的选择。