Back to Details

check-cross-layer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cross-Layer Check

跨层检查

Check if your changes considered all dimensions. Most bugs come from "didn't think of it", not lack of technical skill.
Note: This is a post-implementation safety net. Ideally, read the Pre-Implementation Checklist before writing code.
检查你的变更是否考虑到了所有维度。大多数bug源于“没想到”，而非技术能力不足。
注意：这是一个实现后的安全保障措施。理想情况下，在编写代码之前阅读预实现检查清单。

Related Documents

相关文档

DocumentPurposeTiming
Pre-Implementation ChecklistQuestions before codingBefore writing code
Code Reuse Thinking GuidePattern recognitionDuring implementation
/trellis:check-cross-layer
 (this)		Verification checkAfter implementation
文档用途时机
预实现检查清单编码前的问题排查编写代码前
代码复用思路指南模式识别实现过程中
/trellis:check-cross-layer
 (本文档)		验证检查实现后

Execution Steps

执行步骤

1. Identify Change Scope

1. 确定变更范围

bash
git status
git diff --name-only
bash
git status
git diff --name-only

2. Select Applicable Check Dimensions

2. 选择适用的检查维度

Based on your change type, execute relevant checks below:
根据你的变更类型，执行以下相关检查：

Dimension A: Cross-Layer Data Flow (Required when 3+ layers)

维度A：跨层数据流（涉及3层及以上时必填）

Trigger: Changes involve 3 or more layers
LayerCommon Locations
API/Routes
routes/
, 
api/
, 
handlers/
, 
controllers/
Service/Business Logic
services/
, 
lib/
, 
core/
, 
domain/
Database/Storage
db/
, 
models/
, 
repositories/
, 
schema/
UI/Presentation
components/
, 
views/
, 
templates/
, 
pages/
Utility
utils/
, 
helpers/
, 
common/
Checklist:
  • Read flow: Database -> Service -> API -> UI
  • Write flow: UI -> API -> Service -> Database
  • Types/schemas correctly passed between layers?
  • Errors properly propagated to caller?
  • Loading/pending states handled at each layer?
Detailed Guide: 
.trellis/spec/guides/cross-layer-thinking-guide.md
触发条件：变更涉及3层或更多层级
层级常见位置
API/路由
routes/
, 
api/
, 
handlers/
, 
controllers/
服务/业务逻辑
services/
, 
lib/
, 
core/
, 
domain/
数据库/存储
db/
, 
models/
, 
repositories/
, 
schema/
UI/展示层
components/
, 
views/
, 
templates/
, 
pages/
工具类
utils/
, 
helpers/
, 
common/
检查清单:
  • 读取流程：数据库 -> 服务 -> API -> UI
  • 写入流程：UI -> API -> 服务 -> 数据库
  • 各层之间传递的类型/模式是否正确？
  • 错误是否正确传递给调用方？
  • 各层是否都处理了加载/等待状态？
详细指南：
.trellis/spec/guides/cross-layer-thinking-guide.md

Dimension B: Code Reuse (Required when modifying constants/config)

维度B：代码复用（修改常量/配置时必填）

Trigger:
  • Modifying UI constants (label, icon, color)
  • Modifying any hardcoded value
  • Seeing similar code in multiple places
  • Creating a new utility/helper function
  • Just finished batch modifications across files
Checklist:
  • Search first: How many places define this value?
    bash
    # Search in source files (adjust extensions for your project)
grep -r "value-to-change" src/
  • If 2+ places define same value -> Should extract to shared constant
  • After modification, all usage sites updated?
  • If creating utility: Does similar utility already exist?
Detailed Guide: 
.trellis/spec/guides/code-reuse-thinking-guide.md
触发条件：
  • 修改UI常量（标签、图标、颜色）
  • 修改任何硬编码值
  • 在多个位置看到相似代码
  • 创建新的工具/辅助函数
  • 刚完成跨文件的批量修改
检查清单:
  • 先搜索：这个值在多少个地方定义？
    bash
    # 在源文件中搜索（根据项目调整扩展名）
grep -r "value-to-change" src/
  • 如果2个及以上位置定义了相同的值 -> 应提取为共享常量
  • 修改后，所有使用位置都已更新？
  • 如果创建工具类：是否已有类似的工具类存在？
详细指南：
.trellis/spec/guides/code-reuse-thinking-guide.md

Dimension B2: New Utility Functions

维度B2：新工具函数

Trigger: About to create a new utility/helper function
Checklist:
  • Search for existing similar utilities first
    bash
    grep -r "functionNamePattern" src/
  • If similar exists, can you extend it instead?
  • If creating new, is it in the right location (shared vs domain-specific)?
触发条件：即将创建新的工具/辅助函数
检查清单:
  • 先搜索是否已有类似的工具函数
    bash
    grep -r "functionNamePattern" src/
  • 如果存在类似函数，能否扩展它而非新建？
  • 如果新建，是否放在了正确的位置（共享 vs 领域特定）？

Dimension B3: After Batch Modifications

维度B3：批量修改后

Trigger: Just modified similar patterns in multiple files
Checklist:
  • Did you check ALL files with similar patterns?
    bash
    grep -r "patternYouChanged" src/
  • Any files missed that should also be updated?
  • Should this pattern be abstracted to prevent future duplication?
触发条件：刚完成对多个文件中相似模式的修改
检查清单:
  • 是否检查了所有使用该模式的文件？
    bash
    grep -r "patternYouChanged" src/
  • 是否有遗漏的文件也需要更新？
  • 是否应该将该模式抽象化以避免未来重复？

Dimension C: Import/Dependency Paths (Required when creating new files)

维度C：导入/依赖路径（创建新文件时必填）

Trigger: Creating new source files
Checklist:
  • Using correct import paths (relative vs absolute)?
  • No circular dependencies?
  • Consistent with project's module organization?
触发条件：创建新的源文件
检查清单:
  • 是否使用了正确的导入路径（相对路径 vs 绝对路径）？
  • 没有循环依赖？
  • 与项目的模块组织一致？

Dimension D: Same-Layer Consistency

维度D：同层一致性

Trigger:
  • Modifying display logic or formatting
  • Same domain concept used in multiple places
Checklist:
  • Search for other places using same concept
    bash
    grep -r "ConceptName" src/
  • Are these usages consistent?
  • Should they share configuration/constants?
触发条件：
  • 修改展示逻辑或格式
  • 同一领域概念在多个位置使用
检查清单:
  • 搜索使用同一概念的其他位置
    bash
    grep -r "ConceptName" src/
  • 这些用法是否一致？
  • 它们是否应该共享配置/常量？

Common Issues Quick Reference

常见问题快速参考

IssueRoot CausePrevention
Changed one place, missed othersDidn't search impact scope
grep
before changing
Data lost at some layerDidn't check data flowTrace data source to destination
Type/schema mismatchCross-layer types inconsistentUse shared type definitions
UI/output inconsistentSame concept in multiple placesExtract shared constants
Similar utility existsDidn't search firstSearch before creating
Batch fix incompleteDidn't verify all occurrencesgrep after fixing
问题根本原因预防措施
修改了一处，遗漏了其他位置未搜索影响范围修改前使用
grep
数据在某层丢失未检查数据流追踪数据从源头到目的地的路径
类型/模式不匹配跨层类型不一致使用共享类型定义
UI/输出不一致同一概念在多个位置使用提取共享常量
已有类似工具类未先搜索创建前先搜索
批量修复不完整未验证所有出现的位置修复后使用grep

Output

输出

Report:
  1. Which dimensions your changes involve
  2. Check results for each dimension
  3. Issues found and fix suggestions
报告:
  1. 你的变更涉及哪些维度
  2. 每个维度的检查结果
  3. 发现的问题及修复建议