16gagent/reflections/2026-06-05-nextjs-path.md

Reflection: Next.js src/app/ vs app/ Path Convention

Date: 2026-06-05 | Severity: P0 | Recurrence: 1

Context

Domain Benchmark Suite v1 — frontend-builder-agent.mjs 生成的 Next.js 项目输出到 src/app/ 目录。10/10 项目 Build 失败（0/10 Build）。Next.js App Router 默认 pages directory 是 app/。

Root Cause

Frontend Builder Agent 的初始设计内嵌了错误的路径假设。模板代码输出到 src/app/，但 Next.js app/ router 不从 src/app/ 读取。Tailwind content 配置和 tsconfig paths 也指向了错误路径。

Fix

全局替换：

• src/app/ → app/
• 更新 tsconfig paths 匹配 app/
• 更新 tailwind.config content 匹配 app/**/*.{ts,tsx}

Pattern Class

Path Convention Mismatch — Generator/Builders 有硬编码路径假设，与实际 runtime 的 convention 不一致。

Future Trigger

• Any Next.js project generation
• Any framework-specific builder agent creation
• Any path-dependent code generation

Checklist

• 验证生成器输出目录与目标框架的 default convention 一致
• 在生成器写完第一版后立即跑 build smoke test
• tsconfig paths 与 tailwind content 与 pages directory 三者一致性检查

Recurrence Count

1