工程参考 · 33 篇
AI 编码指南
给 AI Agent 和代码评审者看的工程指南,涵盖工具链、工程实践、技术选型与平台规范,并按任务场景组织阅读顺序。
在项目中使用
在项目目录运行这条命令,然后明确要求 Agent 按本指南执行当前任务。
pnpm dlx skills add fang2hou/ai-coding-guidelines@apply-guidelines也可以不安装 skill,直接把下面的提示词发给 AI Agent。
请按 https://github.com/fang2hou/ai-coding-guidelines 中的指南执行当前任务。
从 PORTAL.md 开始,按任务对应的阅读顺序查阅并应用相关规范。必读基础
开始任何任务前,先读这两篇。
按任务选读
根据手头的任务,按顺序阅读对应的指南链。
新建 TypeScript / 前端项目
构建 TypeScript 后端服务
开发 Python API 服务
UI 样式与圆角细节
iOS 27 / macOS 27 Liquid Glass 应用
测试、Git 提交与 CI/CD
按分类浏览
全部指南按所属技术层分组,便于逐类浏览。
核心原则
1 篇整套指南立身的基本原则:快速校验、收敛选择、解决根本原因。
工程实践
12 篇日常工程实践:编码规范、测试、项目文档、依赖管理、流水线与安全。
- Agent 操作协议开始实质性变更前,AI Agent 应:
- 编写 AGENTS.mdAGENTS.md 是仓库中 AI Agent 的入口文件。Agent 工具在每次会话开始时都会加载它,且上下文空间有限,因此每一行都必须言之有物。
- 架构治理在 ARCHITECTURE.md 中明确记录架构边界和不变量,防止 AI Agent 无意间打破它们。
- 变更纪律每项实质性变更交付评审前,都要按这份清单检查,并遵循操作协议。
- 编码标准遵循所用语言和框架的通行惯例,不要另搞一套私有写法。
- 圆角圆角是一套体系,不要给每个元素单独写死数值:项目只需定义几个固定的设计令牌档位,所有圆角都从中选取。 两条规则涵盖所有情况:单层表面用连续圆角,嵌套表面用同心圆角。
- 依赖管理规范添加依赖之前,按顺序回答以下五个问题:
- 语言政策分别确定以下三种语言,切勿从其中一种推断另一种:
- 流水线这些规则适用于任何系统中的 CI/CD 流水线——GitHub Actions、GitLab CI、CircleCI、Jenkins 或其他系统。所选系统的专属规则见对应的工具链文档。
- 必备项目文档每个项目必须维护 AGENTS.md、README.md、DEVELOPMENT.md 与 CONTRIBUTING.md。项目一旦形成有实际意义的架构边界,ARCHITECTURE.md 也成为必备文档。以 templates/ 下的模…
- 安全严禁向仓库提交任何敏感信息,包括但不限于:
- 测试策略编写测试是为了验证有实际意义的行为,而不是凑覆盖率数字。
工具链
9 篇各语言生态的统一工具链,本地开发与 CI 环境保持完全一致。
- Databricks对于数据和 AI 工作负载,优先选用 Databricks:用 Databricks Apps 托管和管理应用,用 Databricks Jobs 执行定时或自动任务。
- Git 工作流所有项目提交必须遵循 Conventional Commits 规范。
- GitHub ActionsGitHub Actions 是标准 CI/CD 平台;用户未指定流水线系统时,默认选择 GitHub Actions。与工具无关的流水线规则见 流水线。
- Go 工具链TypeScript 与 Python 是 AI 辅助开发的默认语言。Go 不是默认选项,仅当项目确实需要以下能力时才选择 Go:
- mise每个项目必须使用 mise。
- Python 工具链Python 与 TypeScript 是 AI 辅助开发的默认语言,因为它们的库生态和 AI Agent 生态最成熟。
- 质量门禁使用 prek 作为标准的预提交框架。
- Rust 工具链TypeScript 与 Python 是 AI 辅助开发的默认语言。Rust 不是默认选项,仅当项目确实需要以下能力时才选择 Rust:
- TypeScript 工具链TypeScript 和 Python 是 AI 辅助开发的默认语言,因为它们的库生态和 AI Agent 生态最成熟。
库与框架
8 篇前后端、样式与 AI 应用的默认技术栈与选型边界。
- Agentation视情况采用——在前端迭代和测试期间启用 Agentation,将视觉反馈转换为 AI 编码 Agent 可直接使用的结构化上下文。
- 前端框架:Vite 与 Next.js首选——Vite 是默认前端框架;只有项目确实需要全栈 React 能力时才选择 Next.js。
- Go API 技术栈首选——Go Web 框架使用 Echo,请求校验使用 github.com/go-playground/validator/v10。只有依据 Go 工具链 的标准完成 Go 本身的选型论证后,才适用本技术栈。
- Python API 技术栈首选——FastAPI + Pydantic + Uvicorn 是标准的 Python API 技术栈;三者应作为一个整体采用,而不是分别挑选。
- Svelte(Svelte 5 + SvelteKit)视情况采用——Svelte 5 加 SvelteKit 允许用于以开发乐趣为目标的小型个人项目和实验项目。它不是默认选择:生产前端仍使用前端框架中选定的 React 技术栈。
- Tailwind CSS视情况采用——项目已在用 Tailwind,或组件套件依赖 Tailwind 时才使用。新的样式开发默认使用原生 CSS。
- TypeScript 后端技术栈首选——TypeScript 后端服务使用 Hono。默认运行时为 Node.js Active LTS 版本线;Web 标准 API 使服务可移植到 Cloudflare Workers 等其他运行时。模型根据训练数据生成代码,主流且经…
- Vercel AI SDK视情况采用——仅当 Next.js 项目确实要用到 Vercel AI SDK 的流式响应或 UI 集成功能时才使用。
平台规范
3 篇Apple 平台(iOS / macOS 27 Liquid Glass)的设计与实现规范。
- Liquid Glass API 参考面向使用 Xcode 27 构建的 iOS 27 和原生 macOS 27 应用,最低系统版本均设为 27.0。核验日期为 2026-09-06,依据 Apple 文档和 Xcode 27 Beta 构建 27A5252f(iPhoneO…
- Liquid Glass 设计(Apple 平台)面向 iOS 27 与原生 macOS 27 的新应用,优先通过系统导航和控件采用 Liquid Glass。只有标准组件无法满足交互需求时,才添加自定义玻璃效果。最低系统版本设为 iOS 27.0 或 macOS 27.0,使用 Xco…
- Liquid Glass 实现模式这些模式用于通过 Xcode 27 构建的 iOS 27 和原生 macOS 27 应用,对应最低系统版本设为 27.0。优先采用 SwiftUI;自定义集成在 iOS 使用 UIKit,在 macOS 使用 AppKit。共享代码须隔离…