edit | blame | history | raw

C1.source/AGENTS.md - 源码目录规则

适用于 /Users/ar/Projects/Aligner/03-O/C1.source。

当前事实

  • 本目录是 SwiftPM 源码根目录。
  • 本目录不是 Git 根目录；Git 命令在 /Users/ar/Projects/Aligner/03-O 下执行。
  • App 名：Aligner。
  • Bundle ID：com.ar.Aligner。
  • 最低 macOS：14.0。
  • 当前产品入口：只有 quickSwitch。
  • 默认 Quick Switch 快捷键：Option+Tab。

读取顺序

  1. /Users/ar/Projects/Aligner/AGENTS.md
  2. /Users/ar/Projects/Aligner/PROJECT.md
  3. /Users/ar/Projects/Aligner/00-H/初心与Go-No-Go.md
  4. /Users/ar/Projects/Aligner/02-P/plan-progress.markdown
  5. /Users/ar/Projects/Aligner/GLOSSARY.md
  6. /Users/ar/Projects/Aligner/03-O/README.md
  7. /Users/ar/Projects/Aligner/03-O/C1.source/CODEGRAPH.md
  8. 当前任务相关的 Round / 架构文档
  9. UI 修改时读 /Users/ar/Projects/Aligner/DESIGN.md

代码边界

  • 可脱离 App 壳的核心产品逻辑优先放在 Sources/AlignerCore。
  • App 启动、AppKit 窗口、权限 UI、运行时 wiring 放在 Sources/Aligner。
  • 私有 API / 系统集成代码必须隔离在窄的基础设施边界后，当前位置是 Sources/Aligner/Infrastructure/PrivateAPI 或相邻 infrastructure 目录。
  • 业务逻辑应依赖协议，不要散落直接系统调用。
  • 不要手动编辑 .build/。

当前 Quick Switch 规则：

  • 展示最小化窗口。
  • 隐藏 App 窗口不展示。
  • 过滤幽灵窗口和非任务系统浮层。
  • 全屏 App 窗口必须可发现。
  • 永远不要吞掉或阻挡 Command+Option+Esc Force Quit。
  • 非平凡 Quick Switch 改动前，先读 CODEGRAPH.md 中对应 node，再读 node 指向的源码和 QA。
  • 用户要求“冻结版本”时，必须在打 tag 前更新并校验 CODEGRAPH.md。

验证

从 /Users/ar/Projects/Aligner/03-O/C1.source 执行：

swift build
swift test

打包时执行：

/Users/ar/Projects/Aligner/03-O/C3.tools/package-app.sh

如需限制终端输出，使用执行工具的输出上限或写入日志文件，不在标准验证命令后追加截断管道。

如果不能运行验证，说明具体原因和剩余风险。

修改规则

  • 改动范围贴住任务。
  • 行为变化可测试且成本合理时，新增或更新测试。
  • 不要改变 Bundle ID、最低 macOS、签名假设、快捷键语义或权限行为，除非用户明确要求。
  • 不要提交构建产物，除非任务就是打包 / 发布。
  • 不要把参考源码项目里的规则套到本源码目录。