fusion-code-conventions

代码规范

适用场景

当需要依据项目规范审查、编写或解释代码时使用。适用于两个层面：

• 语言规范 — 命名、文件命名、类型系统、TSDoc/XML 文档标准、代码结构、错误处理、异步模式、死代码策略。每种语言都有专门的 Agent 和权威参考文档。
• 跨领域规范 — 每次审查都适用：意图记录（每个不明显的决策都必须有足够完善的文档说明，以便仅凭注释就能重新生成代码）和章程执行（ADR 和贡献者文档是必须遵守的规定；偏离时需要新增决策记录；过时的决策会被标记）。

常见触发场景：

• “这个项目的命名规范是什么？”
• “这个函数的 TSDoc 应该怎么写？”
• “这个文件是否符合我们的代码风格？”
• “检查这里是否违反规范”
• “这里应该使用什么注释风格？”
• “这种写法符合 TypeScript / React / C# / Markdown 的惯用风格吗？”
• “将代码规范应用到这个文件”
• “这些行内注释够完善吗？”
• “这是否违反了任何 ADR？”
• “这个 ADR 还有效吗？”
• “我们有一个 CONTRIBUTING.md——检查这个改动是否符合其中的要求”

不适用场景

• 安全漏洞扫描（请使用专门的安全审查技能）
• 性能分析或基准测试
• 高层架构或系统设计决策
• 在没有审查目标的情况下生成全新代码
• 未经用户明确确认就修改文件

优先级与适用性

此技能提供组织级基准规范。安装在有自身规范的代码库中时，优先级如下（优先级从高到低）：

1. 代码库级策略 — CONTRIBUTING.md、贡献者指南（contribute/）、ADR、.github/copilot-instructions.md、AGENTS.md 或同类文件
2. 工具配置 — biome.json、tsconfig.json、.editorconfig、代码检查工具配置
3. 此技能 — references/*.conventions.md 中的所有规则以及 Agent 模式

当代码库明确缩小适用范围、放宽或与此技能中的某项规则相矛盾时，以代码库策略为准。即使代码偏离此技能的基准，只要符合代码库中记录的规范，就不要将其标记为问题。

如果冲突未记录（没有 ADR、贡献者说明或配置），则将此技能中的规则视为默认规则，并建议团队记录其意图。

维护者须知： 请在 CONTRIBUTING.md、贡献者指南或 ADR 中记录规范覆盖项，以便人类和 Agent 都能以一致的方式发现这些信息。

Agent 模式

Agent	启用条件
agents/typescript.agent.md	TypeScript 命名、TSDoc、类型系统、代码风格、错误处理
agents/react.agent.md	React 组件结构、hooks 规则、无障碍性、键
agents/csharp.agent.md	C# 命名、CQRS 模式、async/await、空值安全、测试
agents/markdown.agent.md	Markdown 结构、frontmatter、链接、提示框、GitHub 专属语法
agents/intent.agent.md	意图记录——在每次代码审查中并行应用
agents/constitution.agent.md	ADR 和贡献者文档执行——项目存在决策记录时并行应用

规范参考文档（各语言的权威规则）：

• references/typescript.conventions.md
• references/react.conventions.md
• references/csharp.conventions.md
• references/markdown.conventions.md

必需输入

如果缺少必需输入或内容不明确，请先询问。

• 目标代码（内联代码片段或文件路径），或具体的规范问题
• 语言或文件类型（如果未提供，则根据内容推断）
• 对于章程检查：ADR 目录和/或贡献者文档的路径（如果未提供，则从常见位置推断——docs/adr/、CONTRIBUTING.md、contribute/）

如果已知开发者的上下文或角色，请查阅 assets/ 中对应的后续问题文件，以便提出有针对性的澄清问题。只询问尚未解答的问题。

• assets/framework-core-developer.follow-up.md — Fusion Framework 内部实现、共享库、框架 API
• assets/react-app.follow-up.md — Fusion React 应用开发
• assets/core-service.follow-up.md — Fusion Core 后端服务（C# / .NET）

说明

第 1 步 — 分类并路由

检测主要语言，然后启用对应的语言 Agent：

• TypeScript（.ts、非组件 .tsx）→ agents/typescript.agent.md
• React（带有 JSX 或 hooks 的 .tsx、组件文件）→ agents/react.agent.md
• 混合 .tsx（TypeScript 类型相关问题 + React 组件相关问题）→ 并行启用两个 Agent
• C#（.cs、.csproj）→ agents/csharp.agent.md
• Markdown（.md、.mdx）→ agents/markdown.agent.md

进行任何代码审查时，始终并行启用：

• agents/intent.agent.md — 每次审查都启用，无论语言是什么
• agents/constitution.agent.md — 项目包含 ADR（docs/adr/、adr/）或贡献者文档（CONTRIBUTING.md、contribute/、.github/copilot-instructions.md）时启用

如果无法确定语言，请先询问。

第 2 步 — 应用或解释规范

每个语言 Agent 会先读取权威参考文件，然后：

• 对于规范问题：解释规则并提供修正后的代码示例
• 对于代码审查：指出偏差、说明规则并展示修正后的版本
• 不要标记项目已在 biome.json 或 .editorconfig 中明确配置的模式

意图 Agent 和章程 Agent 会并行运行，并将发现的问题纳入综合报告。

第 3 步 — 呈现发现

将所有 Agent 的发现整理为一份统一报告：

• 必须修复 — 必须修正：命名违规、导出项缺少 TSDoc、any 类型、违反章程的情况
• 建议修复 — 应当修正：意图注释薄弱、未记录的魔法值、缺乏合理依据的抑制项
• 供参考 — 可考虑：缺少决策记录、过时的 ADR、需要正式记录的隐式例外

对于每项发现：说明规则、涉及的代码，以及修正后的版本或建议采取的措施。

第 4 步 — 应用修正

只应用用户明确批准的修正。使用工作区工具编辑文件。除非文件少于 50 行，否则不要重写整个文件。

预期输出

• 对于规范问题：解释规则，并提供修正后的代码或标记语言示例
• 对于代码审查：提供统一的发现报告（必须修复 / 建议修复 / 供参考），涵盖语言规范、意图质量和章程合规性
• 只有在获得用户明确批准后，才可应用所提议的修正并修改文件

安全与约束

• 未经用户明确确认，绝不修改文件。
• 不要标记项目已通过 biome.json 或 .editorconfig 明确采用的样式选择。
• 不要编造 ADR 内容——只执行并审视实际记录的内容。