fusion-code-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Conventions

代码规范

When to use

适用场景

Use this skill whenever code needs to be reviewed, written, or explained against project conventions. It applies at two layers:

Language conventions — naming, file naming patterns, type system, TSDoc and XML doc standards, code structure, error handling, async patterns, and dead code policy. Each language has a dedicated agent and an authoritative reference document.
Cross-cutting conventions — applied on every code review regardless of language: intent capture (every non-obvious decision must be documented well enough that the code could be regenerated from comments alone) and constitution enforcement (ADRs and contributor docs are law; deviations require a new decision record; stale decisions are flagged for revision).

Typical triggers:

"what are the naming conventions for this project?"
"how should I write TSDoc for this function?"
"does this file follow our code style?"
"review this for convention violations"
"what comment style should I use here?"
"is this idiomatic TypeScript / React / C# / Markdown?"
"apply code conventions to this file"
"are these inline comments good enough?"
"does this violate any ADR?"
"is this ADR still current?"
"we have a CONTRIBUTING.md — check if this change follows it"

每当需要根据项目规范审查、编写或解释代码时，均可使用此技能。它适用于两个层面：

语言规范 —— 命名、文件命名模式、类型系统、TSDoc和XML文档标准、代码结构、错误处理、异步模式以及死代码策略。每种语言都有对应的专属Agent和权威参考文档。
跨领域规范 —— 无论使用何种语言，所有代码审查均需遵循：意图记录（所有非显而易见的决策必须记录充分，仅通过注释即可重新生成代码）和规则执行（ADR和贡献者文档即为准则；若需偏离，需创建新的决策记录；过时的决策会被标记以进行修订）。

典型触发场景：

"该项目的命名规范是什么？"
"我应该如何为这个函数编写TSDoc？"
"这个文件是否符合我们的代码风格？"
"审查此代码是否存在规范违规情况"
"我在这里应该使用哪种注释风格？"
"这是符合规范的TypeScript / React / C# / Markdown写法吗？"
"为这个文件应用代码规范"
"这些内联注释是否足够完善？"
"这是否违反了任何ADR？"
"这个ADR是否仍然有效？"
"我们有CONTRIBUTING.md —— 检查此变更是否符合要求"

When not to use

不适用场景

Do not use this skill for:

Security vulnerability scanning (use a dedicated security review skill)
Performance profiling or benchmarking
High-level architecture or system design decisions
Generating net-new code without a review target
Mutating files without explicit user confirmation

请勿将此技能用于：

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

Agent modes

Agent模式

Agent	Activated for
`agents/typescript.agent.md`	TypeScript naming, TSDoc, type system, code style, error handling
`agents/react.agent.md`	React component structure, hooks rules, accessibility, keys
`agents/csharp.agent.md`	C# naming, CQRS patterns, async/await, null safety, testing
`agents/markdown.agent.md`	Markdown structure, frontmatter, links, callouts, GitHub-specific syntax
`agents/intent.agent.md`	Intent capture — applied in parallel on every code review
`agents/constitution.agent.md`	ADR and contributor doc enforcement — applied in parallel when project has decision records

Convention references (authoritative rules per language):

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

Agent	激活场景
`agents/typescript.agent.md`	TypeScript命名、TSDoc、类型系统、代码风格、错误处理
`agents/react.agent.md`	React组件结构、Hooks规则、可访问性、Keys
`agents/csharp.agent.md`	C#命名、CQRS模式、async/await、空安全、测试
`agents/markdown.agent.md`	Markdown结构、前置元数据、链接、提示框、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
```

Required inputs

必要输入

If required inputs are missing or ambiguous, ask before proceeding.

Target code (inline snippet or file path) or a specific convention question
Language or file type (inferred from content if not provided)
For constitution checks: path to ADR directory and/or contributor docs (inferred from common locations —
```
docs/adr/
```
,
```
CONTRIBUTING.md
```
,
```
contribute/
```
— if not provided)

When the developer's context or persona is known, consult the matching follow-up file in

assets/

for targeted clarifying questions before reviewing. Ask only the relevant unanswered questions.

```
assets/framework-core-developer.follow-up.md
```
— Fusion Framework internals, shared libraries, framework APIs
```
assets/react-app.follow-up.md
```
— Fusion React app development
```
assets/core-service.follow-up.md
```
— Fusion Core backend services (C# / .NET)

若必要输入缺失或不明确，请在执行前询问用户。

目标代码（内联代码片段或文件路径）或具体的规范问题
语言或文件类型（若未提供，可从内容中推断）
规则检查：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）

Instructions

操作步骤

Step 1 — Classify and route

步骤1 —— 分类与路由

Detect the primary language of the target code or question, then activate the matching language agent:

TypeScript (
```
.ts
```
, non-component
```
.tsx
```
) →
```
agents/typescript.agent.md
```
React (
```
.tsx
```
with JSX or hooks, component files) →
```
agents/react.agent.md
```
Mixed
```
.tsx
```
(TypeScript type concerns + React component concerns) → both agents in parallel
C# (
```
.cs
```
,
```
.csproj
```
) →
```
agents/csharp.agent.md
```
Markdown (
```
.md
```
,
```
.mdx
```
) →
```
agents/markdown.agent.md
```

Always activate in parallel on any code review:

```
agents/intent.agent.md
```
— every review, regardless of language

agents/constitution.agent.md

— when the project has ADRs (

docs/adr/

adr/

) or contributor docs (

CONTRIBUTING.md

contribute/

.github/copilot-instructions.md

)

If the language cannot be determined from context, ask before proceeding.

检测目标代码或问题的主要语言，然后激活对应的语言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
```

所有代码审查均需并行激活以下Agent：

```
agents/intent.agent.md
```
—— 所有审查，无论语言

agents/constitution.agent.md

—— 当项目存在ADR（

docs/adr/

、

adr/

）或贡献者文档（

CONTRIBUTING.md

、

contribute/

、

.github/copilot-instructions.md

）时

若无法从上下文确定语言，请先询问用户。

Step 2 — Apply or explain conventions

步骤2 —— 应用或解释规范

Each language agent reads its authoritative reference file first, then:

For convention questions: answers directly with a rule explanation and a corrected code example
For code review: identifies deviations, states the rule, shows the corrected version
Does not flag patterns the project has explicitly configured in
```
biome.json
```
or
```
.editorconfig
```

The intent and constitution agents run in parallel and contribute their findings to the combined report.

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

对于规范问题：直接回答规则解释并提供修正后的代码示例
对于代码审查：识别偏差、说明规则、展示修正后的版本
不会标记项目在
```
biome.json
```
或
```
.editorconfig
```
中明确配置的模式

意图和规则Agent会并行运行，并将其发现整合到综合报告中。

Step 3 — Present findings

步骤3 —— 呈现发现结果

Organise all findings from all agents into a unified report:

Required — must fix: naming violations, missing TSDoc on exports,
```
any
```
types, constitutional violations
Recommended — should fix: weak intent comments, undocumented magic values, unjustified suppressions
Advisory — consider: missing decision records, stale ADRs, implicit exceptions that should be formalised

For each finding: state the rule, the affected code, and the corrected version or recommended action.

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

必须修复：命名违规、导出项缺失TSDoc、
```
any
```
类型、规则违规
建议修复：意图注释薄弱、未记录的魔法值、无正当理由的抑制
参考建议：缺失决策记录、过时的ADR、应正式化的隐式异常

对于每个发现：说明规则、受影响的代码、修正后的版本或建议操作。

Step 4 — Apply corrections

步骤4 —— 应用修正

Apply only corrections the user explicitly approves. Edit files using workspace tools. Do not rewrite entire files unless the file is under 50 lines.

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

Expected output

预期输出

For convention questions: a rule explanation with a corrected code or markup example
For code review: a unified findings report (Required / Recommended / Advisory) covering language conventions, intent quality, and constitutional compliance
Offered corrections with the user's explicit approval before any file is mutated

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

Safety & constraints

安全与约束

Never mutate files without explicit user confirmation.
Do not flag style choices the project has explicitly opted into via
```
biome.json
```
or
```
.editorconfig
```
.
Do not invent ADR content — only enforce and challenge what is actually documented.

未经用户明确确认，绝不修改文件。
不会标记项目通过
```
biome.json
```
或
```
.editorconfig
```
明确选择的风格选项。
不得编造ADR内容——仅执行和质疑已实际记录的内容。