Headscale Admin 基于 Next.js App Router，核心代码位于 src/。src/app/ 按路由段划分模块，admin/ 下将页面、布局与加载状态放在同级目录，便于协同开发。通用组件与 shadcn 风格的 UI 原子保存在 src/components/，领域逻辑与数据请求封装放在 src/lib/。静态资源（图标、SVG、公开脚本）位于 public/。导入内部模块时使用 @/ 别名保持路径简洁。
执行 bun install 安装依赖（仓库提供 bun.lock）。本地调试使用 bun dev，Next.js 将以 Turbo 模式启动。发布前运行 bun build，并用 bun start 验证产物。提交前务必执行 bun lint，该命令会联合 TypeScript 与 ESLint 校验。样式层面的定制集中在 tailwind.config.ts 与 postcss.config.js，统一在配置文件中管理设计令牌。
优先编写 TypeScript 函数组件，并为 props 提供显式类型。组件使用 PascalCase，工具函数使用 camelCase，路由目录推荐 kebab-case。将页面逻辑与对应的 Server/Client 组件放在同一个路由目录中，便于检查数据流。统一使用两个空格缩进，当 JSX 属性超过一行时断行排列。复用 src/components/ui/ 中的基础原子，并尽量沿用 Tailwind 公共类（如 container、bg-secondary），避免散落的自定义 CSS。
- 请注意禁止修改
src/components/ui/中的基础原子，禁止修改tailwind.config.ts与postcss.config.js中的配置。 - 禁止修改
src/app/globals.css中的配置。
当前尚未落地自动化测试，稳定后优先引入 Vitest 或 Playwright。新增测试文件请命名为 *.test.tsx 并与待测文件放在同一目录。暂未覆盖的场景需在 PR 中写明手动验证步骤，尤其是机器生命周期、用户管理与设置面板，确保审阅者能够复现。
遵循现有提交历史，标题使用简短祈使句，可根据需要添加作用域前缀（例如 chore:、feat: 或中文描述）。合并请求需要概述改动、列出手动验证或附带截图，并关联对应的 Headscale 需求。提交前确认本地 bun lint 通过，避免 CI 失败。
启动前复制 .env.example 为 .env.local，补充 Headscale 接口地址与访问令牌；.env.local 已被忽略，请勿提交密钥。生产环境的配置更新需通过团队安全渠道同步，禁止将敏感值写入代码。
- 以瞎猜接口为耻，以认真查询为荣。
- 以模糊执行为耻，以寻求确认为荣。
- 以臆想业务为耻，以复用现有为荣。
- 以创造接口为耻，以主动测试为荣。
- 以跳过验证为耻，以人类确认为荣。
- 以破坏架构为耻，以遵循规范为荣。
- 以假装理解为耻，以诚实无知为荣。
- 以盲目修改为耻，以谨慎重构为荣。