【Kiro】Steering：如何通过引导文件实现智能项目导航

1. 为什么你需要Kiro的引导文件功能第一次接触Kiro的引导文件功能时我其实有点怀疑不就是几个Markdown文档吗能有多大用处直到团队里来了两个新成员我才真正体会到它的价值。当时我们正在开发一个React项目新人提交的组件代码风格五花八门——有的用单引号有的用双引号有的组件拆分成多个文件有的全部挤在一个文件里。更头疼的是API接口命名有人用驼峰式有人用下划线整个项目就像打满了补丁的旧衣服。这就是product.md、tech.md和structure.md这三个基础文件发挥作用的时候了。它们就像是项目的宪法明确规定着各种规范。比如在tech.md中我们写明前端使用React 18TypeScript代码风格遵循Airbnb规范在structure.md里我们规定组件必须使用PascalCase命名每个组件单独建立文件夹包含index.tsx、styles.module.css和types.ts。神奇的是当新人通过Kiro生成代码时自动就会符合这些规范。最让我惊喜的是这些文件不仅仅是静态文档。当我们在tech.md中添加了优先使用TanStack Query进行数据请求的说明后Kiro生成的代码示例就会自动采用这个库而不是直接写fetch。这比在团队群里反复强调记得用QueryClient有效多了。2. 基础引导文件详解2.1 product.md项目的灵魂文档很多技术团队容易忽视product.md的价值觉得这是产品经理该关心的事。但实际开发中我经常遇到这样的情况开发某个功能时技术方案A实现简单但扩展性差方案B前期投入大但长期收益高。如果没有清晰的产品目标作为判断依据技术决策就容易变成个人偏好之争。我们的电商项目product.md是这样写的# 产品目标 - 为中小商家提供零门槛的移动端店铺解决方案 - 核心价值3分钟快速开店 - 关键指标店铺创建完成率、商品上架速度 # 用户痛点 - 传统方案需要配置域名、服务器等专业技术 - 移动端适配差操作流程复杂 - 营销工具学习成本高当Kiro理解这些背景后它给出的建议就会明显不同。比如在设计图片上传组件时它会优先考虑默认集成CDN加速解决服务器配置痛点自动生成多种尺寸缩略图移动端适配一键添加水印功能满足商家防盗图需求2.2 tech.md技术选型的导航仪去年我们团队在状态管理方案上浪费了两周时间——有人想用Zustand有人坚持Redux Toolkit还有人提议Jotai。最后在tech.md中明确写道# 前端技术栈 - 状态管理Redux Toolkit已有多人熟悉现有项目兼容 - 禁止使用MobX版本升级风险大 - 备选方案仅在小型项目考虑Zustand # 版本规范 - React ≥18.2 - TypeScript strict模式 - ESLint配置继承自airbnb-typescript这个文件最妙的地方在于它的动态性。当有人问Kiro要不要试试新的状态管理库时Kiro会直接引用tech.md的内容回应根据项目技术规范建议保持使用Redux Toolkit原因如下...这比技术主管天天在群里强调别乱换库有效多了。2.3 structure.md项目的地基蓝图好的项目结构就像精心设计的城市布局让所有代码都能找到自己的位置。我们的structure.md是这样定义React组件规范的# 组件结构 components/ ├── Button/ │ ├── index.tsx // 主逻辑 │ ├── types.ts // 类型定义 │ ├── styles.module.css │ └── __tests__/ // 测试文件 # 命名约定 - 组件PascalCase (如UserProfile) - 工具函数camelCase - 常量UPPER_CASE - 接口类型I前缀 (如IUser)当开发者问Kiro应该把样式文件放在哪里时Kiro会自动根据structure.md给出符合项目规范的答案而不是通用的建议。这种一致性让代码审查工作量减少了至少30%。3. 高级引导技巧实战3.1 条件包含精准的上下文触发刚开始我总觉得所有引导文件都应该always包含直到项目越来越大Kiro的反应开始变慢。后来发现condition包含模式才是王道。比如我们有个api-guide.md文件--- inclusion: app/api/**/* --- # API设计规范 - 路由命名/api/v{version}/{resource} - 错误码 - 400: 客户端参数错误 - 503: 第三方服务不可用 - 必须包含X-Request-ID头这样只有当开发者处理/api目录下的文件时这些规范才会自动生效。既保证了相关性又避免了不必要的性能开销。实测下来这种条件包含能让Kiro的响应速度提升40%以上。3.2 文件引用让文档永不过期传统文档最大的问题就是容易过时。我们采用#[[file:]]语法实现了文档与代码的实时联动。比如在testing.md中# 单元测试示例 参考最新实现 #[[file:src/components/Button/__tests__/index.test.tsx]]这样当Button组件的测试文件更新时文档中的示例自动同步更新。再也不用担心文档说应该这样写测试而实际代码却是另一种风格了。4. 从混乱到秩序的转型案例去年接手的一个遗留项目让我深刻体会到引导文件的威力。这个项目的React组件有3种写法类组件、函数组件React.memo、函数组件自定义shouldUpdate。API响应体有时是{data: {...}}有时直接返回{...}甚至还有带success字段的版本。我们分三步进行了改造建立基准线用Kiro分析现有代码自动生成初始的tech.md和structure.mdkiro analyze --output.kiro/steering/tech.md kiro analyze --structure .kiro/steering/structure.md渐进式改造创建migration-guide.md用条件包含只在修改文件时生效--- inclusion: manual --- # 改造指南 1. 遇到类组件时#refactor-to-function 2. 发现旧API格式#legacy-api-adapter自动化检查在CI流程中加入Kiro验证steps: - name: Validate steering run: kiro validate --strict6个月后这个项目的代码一致性评分从最初的32分提升到了89分新成员上手时间缩短了60%。最让我意外的是当我们需要从Ant Design迁移到MUI时只需要更新tech.md中的UI库配置Kiro就能自动建议相应的组件替换方案。