使用ai编写xml布局时加快速度AGENTS.md

AGENTS.md

本文件只约束 Android 原生项目中 res/layout/*.xml 布局文件的编写与修改。除非用户明确要求，不修改 Kotlin/Java 业务代码、Manifest、Gradle 配置或其他功能逻辑。

默认快速模式

• 默认以最小读取、最小修改和最小验证完成需求；除非用户明确要求“完整验证”，不主动扩大检查与验证范围。
• 简单布局修改只读取目标布局、直接引用该布局的类，以及本次修改实际涉及的资源文件；不例行扫描整个项目。
• 搜索 ID、样式或资源引用时，优先限定在目标功能目录和直接关联文件。只有无法定位引用或发现跨模块影响时，才扩大搜索范围。
• 多个连续的小修改合并后统一验证一次，不在每次局部编辑后重复运行相同检查。
• 纯布局属性调整默认只运行目标 XML 的语法检查，例如 xmllint --noout <目标文件>；不默认运行 Gradle 任务。
• 新增或删除 ID、Drawable、Style、String，或改变 ViewBinding 结构时，可按风险运行一次目标模块的资源处理任务；不直接升级为完整构建。
• 用户明确要求修改 Kotlin/Java 点击事件等简单逻辑时，只检查目标类与对应 Binding ID；确有必要时仅运行一次目标模块编译。
• 默认不运行 assembleDebug、lintDebug、全项目测试、APK 安装、设备启动或截图验证。
• 仅在用户明确要求“完整验证”，或修改涉及公共 Theme、Manifest、Gradle、跨模块资源和高风险公共布局时，执行更大范围检查；执行前先说明原因。
• 未执行完整构建或真机验证时，在最终说明中简要标明，不把未执行的验证描述为已通过。

修改前检查

• 先阅读目标布局及直接引用该布局的 Activity/Fragment/Adapter；仅在本次修改实际涉及对应资源时，再读取 styles.xml、themes.xml、colors.xml、dimens.xml 或 strings.xml。
• 判断项目使用 ViewBinding、DataBinding 还是普通 findViewById，保持现有方式。
• 优先复用项目已有样式、组件、资源和命名，不重复创建相同资源。
• 保留用户已有修改，只调整完成布局需求所必需的内容。

XML 基本规范

• XML 声明使用：

<?xml version="1.0" encoding="utf-8"?>

• 根节点按需声明 Android 与预览命名空间：

xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
xmlns:tools="http://schemas.android.com/tools"

• 属性按项目现有格式排列；没有既有规则时，优先按 android:id、尺寸、位置、外观、行为、tools:* 的顺序组织。
• ID 使用小写下划线命名并表达用途，例如 tv_title、iv_cover、btn_retry、rv_content。
• 不添加无意义的容器、注释或占位 View。
• tools:* 属性仅用于 Android Studio 预览，不能依赖它实现运行时效果。

布局结构

• 优先沿用项目现有布局体系；新建复杂页面时通常优先使用 ConstraintLayout。
• 在 ConstraintLayout 中，需要由约束决定宽度或高度时使用 0dp，并提供完整约束。
• 每个 View 必须具有确定的位置关系，避免缺少水平或垂直约束。
• 避免多层 LinearLayout、FrameLayout 嵌套；能减少一层容器时应减少。
• 不使用负 margin 修正布局。重叠效果应使用约束、translation 或适合的父容器实现。
• 不使用空白 View 制造间距，使用 margin、padding、Guideline、Barrier 或项目已有间距组件。
• ScrollView 和 NestedScrollView 只能有一个直接子 View；根据需求正确配置 fillViewport。
• RecyclerView 条目布局的根节点高度通常使用 wrap_content，除非设计明确要求固定高度或占满父容器。
• 避免在 RecyclerView 条目中使用成本较高且不必要的深层嵌套、权重和重复背景。

尺寸与间距

• 布局尺寸、margin、padding 和圆角使用 dp；文本大小也使用 dp。
• 不使用 px，不通过空格或换行字符控制视觉间距。
• 优先引用已有 @dimen/...；同一设计值多处使用时应提取为尺寸资源。
• 不随意使用固定宽高。文本一定使用wrap_content，除非可能超出容器才使用约束。动态内容优先使用 wrap_content、约束或合理的最小/最大尺寸。对于和屏幕或父布局宽高相同的使用match_parent。
• 图标按钮和主要可点击控件应提供至少约 48dp × 48dp 的触控区域，视觉图标可以更小。
• 使用 paddingStart、paddingEnd、layout_marginStart 和 layout_marginEnd，避免仅使用 left/right，从而支持 RTL。
• 布局需要贴近状态栏、导航栏或全面屏边缘时，先沿用项目已有 WindowInsets 处理方式，不自行叠加不可靠的固定高度。

文本与本地化

• 用户可见文本必须引用 @string/...，不要在布局中硬编码。
• 示例文本使用 tools:text，不要通过 android:text 写入仅供预览的内容。
• 文本控件应考虑翻译后长度变化，避免不必要的固定宽度和单行限制。
• 确需单行时明确设置 android:maxLines="1" 和合适的 android:ellipsize。
• 文本颜色、字号、字重和行高优先复用 TextAppearance 或项目已有样式。
• 不通过多个空格、全角空格或特殊字符实现对齐。

颜色、背景与图片

• 颜色引用 @color/... 或主题属性，例如 ?attr/colorPrimary，不要在布局中直接写十六进制颜色。
• 背景、描边、圆角和状态效果优先引用已有 Drawable 或 Style。
• 图片使用语义明确的 @drawable/... 或 @mipmap/... 资源，并设置符合设计的 scaleType。
• ImageView 必须明确处理无障碍描述：有语义的图片使用 @string/...，纯装饰图片使用 android:contentDescription="@null"。
• 不使用低分辨率图片放大填充大区域；保持正确宽高比，避免非预期拉伸。
• 图标着色优先沿用项目现有 tint 方案，不直接复制多份仅颜色不同的资源。

交互与可访问性

• 可点击 View 应具有清晰的点击区域、可用状态和按压/聚焦反馈。
• 不只依赖颜色表达选中、错误或禁用状态。
• 输入框应设置正确的 inputType、hint、IME action，并引用字符串资源。
• 重要控件应具备可理解的 content description、label 或 hint。
• 装饰元素不应被无障碍服务重复朗读。
• 不为了点击事件把整个大型区域设为可点击，除非产品交互明确如此。

样式与复用

• 同类 View 的重复属性优先提取到项目已有 Style 系统，但不要为只使用一次的简单属性创建无意义样式。
• 公共布局块只有在真实复用时才使用 <include>；使用 <merge> 前确认父布局和 inflate 方式兼容。
• 保持 Material Components、AppCompat 或项目自定义组件的一致性，不在同一页面随意混用不同设计体系。
• 不擅自修改全局 Theme 来解决单个页面问题，除非用户明确要求全局效果。

DataBinding 与 ViewBinding

• 项目未启用 DataBinding 时，不添加 <layout> 根节点或表达式语法。
• 项目使用 DataBinding 时，变量和表达式保持简单；复杂业务逻辑放在 ViewModel 或绑定适配器中。
• 不随意重命名已有 ID，因为这会改变生成的 ViewBinding/DataBinding 字段并影响调用代码。
• 必须重命名或新增 ID 时，检查所有引用位置，确保不会造成编译错误。

预览与兼容性

• 可以使用 tools:text、tools:src、tools:visibility、tools:itemCount 等改善预览，但运行时属性必须单独正确配置。
• 检查常见小屏幕、长文本、字体放大、深色模式和 RTL 下的布局表现。
• 夜间模式需要不同资源时，使用项目已有的 values-night 或 drawable-night 结构。
• 不使用高于项目 minSdk 的仅新版本属性，除非已有兼容方案或资源限定目录。

禁止事项

• 不硬编码用户可见文本、颜色和重复尺寸。
• 不使用绝对坐标定位普通页面元素。
• 不通过负 margin、透明占位图或空 View 掩盖布局问题。
• 不删除无障碍属性、测试依赖的 ID 或自动化测试标签。
• 不编辑 build/ 中生成的布局或 Binding 文件。
• 不为消除警告而使用 tools:ignore，除非确认警告不适用于该场景并说明原因。

验证要求

• XML 必须可被 Android 资源编译器解析，引用的 ID、字符串、颜色、尺寸、样式和图片资源必须存在。
• 默认快速模式下，优先执行目标文件语法检查：

xmllint --noout <目标布局路径>

• 涉及资源引用或 ViewBinding 结构变化、且局部检查不足时，可运行目标模块资源处理任务：

./gradlew :app:processDebugResources

• 用户要求“完整验证”时，再根据改动范围运行：

./gradlew assembleDebug
./gradlew lintDebug

• Android Studio Layout Preview 或设备/模拟器检查不作为默认步骤；仅在用户要求、复杂视觉改版或局部检查无法确认结果时执行。

• 最终说明应列出修改的布局文件、主要视觉变化、执行的验证以及仍未验证的设备或状态。

• 使用Figma时，图片用Figma REST API 按 scale=3 原生导出到drawable-xxxhdpi下，背景版一般不包含文字，能切整个就不用分开切

• 文字颜色渐变使用com.wondura.zurvik.app.ui.StrokeTextView