fleur-harness

Fleur Harness

当任务不只是改一段代码，而是要提升 fleur 的可维护性、agent 可读性、架构约束或长期执行可靠性时，使用这个 skill。

核心原则：AGENTS.md 是仓库入口地图，docs/architecture/ 是当前项目状态、代码根、职责边界和架构事实入口，docs/ 是记录系统，测试和脚本是可执行约束。不要把长期规则只留在一次性提示或聊天上下文里。

适用场景

• 复杂重构、跨模块改动、架构边界调整。
• 新增数据源、Dagster asset、dbt 模型、迁移或长期运行任务。
• 维护 AGENTS.md、ADR、RFC、plan、optimize 文档、job report 或 repo skill。
• 把重复出现的问题沉淀为测试、脚本、文档规则或专用 skill。
• 检查文档是否过期、重复、互相冲突或没有对应机械验证。

工作循环

1. 先读地图：从 AGENTS.md、docs/README.md 和相关 docs/architecture/ 入口确认项目结构、命令、边界和质量门禁。
2. 再分流落点：根据需求影响范围决定进入 RFC、plan、ADR、jobs、references、design、archive 或直接修改。
3. 再读事实：用 rg/find 查真实代码、测试、现有文档和最近报告，不用旧文档替代当前代码。
4. 明确意图：小变更可直接执行；复杂方案写 docs/RFC/，跨阶段实施写 docs/plans/，长期约束写 docs/ADR/。
5. 编码约束：反复出现的 review 意见或架构偏好，优先沉淀为测试、脚本、skill 或 AGENTS/docs 路由。
6. 验证闭环：按改动范围运行最小可证明的检查，并在文档中记录无法验证的原因。
7. 清理熵增：发现过期文档、废弃计划、重复规则或源码噪声时，随任务一并收敛，避免继续复制坏模式。

文档路由

• docs/README.md：docs 总入口，提供按当前架构查事实和按文档类型追溯的入口。
• docs/architecture/：当前项目状态、代码根、职责边界、运行入口、质量门禁、架构边界和 dbt layer 模型语义；新增长期系统、应用、服务或子域时同步维护。
• AGENTS.md：repo 入口地图，只放稳定目录、命令、边界和 skill 路由；不要扩展成百科。
• docs/ADR/：已经接受的长期决策；当行为应长期稳定且影响后续设计时新增或更新。
• docs/RFC/：方案讨论和历史设计；实现完成或废弃后移动到 archive/ 或在文档中标明状态。
• docs/plans/：复杂执行计划、阶段拆分、验收标准；活跃计划保留在顶层，完成后归档；新增、归档或改名 active plan 后同步维护 docs/plans/README.md。
• docs/issues/：技术债、实现漂移、质量扫描、维护性审计和治理建议入口。
• docs/jobs/reports/：实际运行、回填、重跑和数据核验记录；必须包含命令、时间、范围和结果。
• docs/architecture/dbt_layer/：dbt layer 和模型设计文档，记录模型语义、字段边界和对应 SQL/YAML。
• docs/references/：远端接口、OpenAPI、数据字典、样例图片、服务器协议等可查事实。
• docs/skills/：可复用 agent 操作手册；只保留 SKILL.md 和必要 references/scripts/assets。

架构事实文档写法

docs/architecture/*.md 是当前事实入口，不是新的一套 RFC 或 README 复制品。架构事实文档应保持短而可导航，优先包含：

• 状态和代码根。
• 职责、非职责和主要依赖。
• 运行入口和最小质量门禁。
• 相关当前文档、ADR、RFC、plan、job report、reference 和 skill 指针。
• 待决问题。

架构事实文档不应承载长篇设计、完整 API 规格、字段字典、执行计划或运行报告；这些内容留在对应生命周期目录中，再由架构事实文档链接。

文档地图阅读顺序

处理 harness、架构、长期维护或文档治理任务时，按下面顺序读文档；只在任务相关时深入，不要无差别通读整个 docs/。

1. AGENTS.md：确认项目入口、命令约束、质量门禁、MCP 路由和 skill 路由。
2. docs/README.md：确认 docs 当前架构事实入口、文档类型入口、目录职责、状态模型和归档规则。
3. docs/architecture/README.md 和 docs/architecture/project-status.md，再读相关 docs/architecture/*.md：确认当前代码根、职责边界、运行入口、质量门禁和相关文档指针。
4. docs/architecture/ 中与该子域相关的当前架构文档：确认跨模块边界、依赖方向和禁止模式。
5. docs/ADR/README.md，再读相关 docs/ADR/*.md：确认已经接受且仍应遵守的长期决策。
6. 活跃设计与执行文档：先读相关 docs/RFC/*.md，再读相关 docs/plans/*.md，确认目标、非目标、阶段和验收标准。
7. 运行事实：涉及回填、重跑、数据核验、性能或生产结果时，读 docs/jobs/README.md、docs/jobs/dagster-backfill-2026.md 和相关 docs/jobs/reports/*.md。
8. 接口与数据事实：涉及远端 API、schema、样例、数据契约或字典时，读相关 docs/references/README.md、docs/references/openapi/、docs/references/remote_endpoint/、docs/references/data_dict/、docs/references/remote_server/。
9. 复用手册：涉及具体 agent 操作时，读相关 docs/skills/*/SKILL.md，并遵守其中更具体的 runbook。
10. 历史材料：docs/RFC/archive/、docs/plans/archive/ 和 docs/issues/ 只用于追溯背景；不得把归档内容当作当前事实，除非架构事实文档、当前代码或活跃文档再次确认。