scan-effect-solutions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Effect Solutions Compliance Audit

Effect Solutions合规审计

Scan repository against Effect TypeScript best practices from effect.solutions. Use this skill to perform systematic audits of Effect code compliance.

对照effect.solutions提供的Effect TypeScript最佳实践扫描代码仓库。使用此Skill对Effect代码合规性进行系统化审计。

Prerequisites

前置条件

Before scanning, load current recommendations:

bash

effect-solutions list

Read targeted references:

text

references/error-handling.md
references/testing-layers.md

Load the effect-ts skill for best practices context:

skill({ name: "effect-ts" })

扫描前，请加载当前推荐配置：

bash

effect-solutions list

阅读指定参考文档：

text

references/error-handling.md
references/testing-layers.md

加载effect-ts Skill以获取最佳实践上下文：

skill({ name: "effect-ts" })

Audit Checklist

审计检查清单

1. TypeScript Configuration

1. TypeScript配置

Check

tsconfig.base.json

(or

tsconfig.json

) for:

```
exactOptionalPropertyTypes: true
```
```
strict: true
```
```
noUnusedLocals: true
```
```
declarationMap: true
```
```
sourceMap: true
```
Effect Language Service plugin configured
Correct
```
module
```
setting for project type (preserve/bundler for apps, NodeNext for libraries)

Run:

effect-solutions show tsconfig

检查

tsconfig.base.json

（或

tsconfig.json

）是否包含：

```
exactOptionalPropertyTypes: true
```
```
strict: true
```
```
noUnusedLocals: true
```
```
declarationMap: true
```
```
sourceMap: true
```
已配置Effect语言服务插件
针对项目类型设置正确的
```
module
```
（应用使用preserve/bundler，库使用NodeNext）

运行命令：

effect-solutions show tsconfig

2. Services & Layers Pattern

2. 服务与分层模式

Search for Effect services and check:

Are services defined with
```
Context.Tag
```
?
Do tag identifiers use
```
@path/ServiceName
```
pattern?
Are layers defined with
```
Layer.effect
```
or
```
Layer.sync
```
?
Is there a single
```
Effect.provide
```
at entry point?

Run:

effect-solutions show services-and-layers

搜索Effect服务并检查：

是否使用
```
Context.Tag
```
定义服务？
标签标识符是否采用
```
@path/ServiceName
```
格式？
是否使用
```
Layer.effect
```
或
```
Layer.sync
```
定义分层？
入口点是否仅有一个
```
Effect.provide
```
？

运行命令：

effect-solutions show services-and-layers

3. Data Modeling

3. 数据建模

Check for:

Use of
```
Schema.Class
```
for records
Use of
```
Schema.TaggedClass
```
for variants
Branded types for primitives (IDs, emails, etc.)
Pattern matching with
```
Match.valueTags
```

Run:

effect-solutions show data-modeling

检查是否：

使用
```
Schema.Class
```
定义记录
使用
```
Schema.TaggedClass
```
定义变体
为原始类型（ID、邮箱等）使用品牌类型
使用
```
Match.valueTags
```
进行模式匹配

运行命令：

effect-solutions show data-modeling

4. Error Handling

4. 错误处理

Check for:

Use of
```
Schema.TaggedError
```
for domain errors
Proper error recovery with
```
catchTag
```
/
```
catchTags
```
Appropriate use of defects vs typed errors

Run:

effect-solutions show error-handling

检查是否：

使用
```
Schema.TaggedError
```
定义领域错误
使用
```
catchTag
```
/
```
catchTags
```
进行正确的错误恢复
合理区分缺陷与类型化错误

运行命令：

effect-solutions show error-handling

5. Configuration

5. 配置

Check for:

Use of
```
Schema.Config
```
for validation
Config service layer pattern
```
Config.redacted
```
for secrets

Run:

effect-solutions show config

检查是否：

使用
```
Schema.Config
```
进行验证
采用配置服务分层模式
使用
```
Config.redacted
```
处理敏感信息

运行命令：

effect-solutions show config

6. Testing

6. 测试

Check for:

Use of
```
@effect/vitest
```
```
it.effect()
```
for Effect tests
Test layer composition patterns

Run:

effect-solutions show testing

检查是否：

使用
```
@effect/vitest
```
使用
```
it.effect()
```
编写Effect测试
采用测试分层组合模式

运行命令：

effect-solutions show testing

7. Runtime Usage Anti-Pattern (

Effect.runPromise

in Production)

7. 运行时使用反模式（生产环境中的

Effect.runPromise

）

Search for

Effect.runPromise

in production code (exclude

__tests__/

*.test.ts

agent-tools/

Effect.runPromise
uses the default runtime with NO layers — no tracer, no config, no observability. Effect spans (

Effect.fn

Effect.withSpan

) will be invisible to Sentry/OpenTelemetry.

Production code MUST use

runtime.runPromise

(from

ManagedRuntime

effect-runtime.ts

) which includes

AppLayer

with

SentryTracingLive

If
```
runtime.runPromise
```
is not possible (circular deps), the code MUST add
```
Effect.provide(SentryTracingLive)
```
to the pipe chain
Test files are exempt (they provide their own layers)

Search patterns:

Effect.runPromise(

apps/web-app/src/

(excluding

__tests__/

)

Effect.runSync(

apps/web-app/src/

(excluding

__tests__/

)

Report each occurrence with:

File path and line
Whether it's using
```
runtime.runPromise
```
(✅) or bare
```
Effect.runPromise
```
(❌)
Whether
```
SentryTracingLive
```
is provided in the pipe chain (fallback ✅)

Run:

effect-solutions show services-and-layers

在生产代码中搜索

Effect.runPromise

（排除

__tests__/

、

*.test.ts

、

agent-tools/

目录）。

Effect.runPromise
使用默认运行时，不包含任何分层 —— 没有追踪器、没有配置、没有可观测性。Effect span（

Effect.fn

、

Effect.withSpan

）在Sentry/OpenTelemetry中不可见。

生产代码必须使用

runtime.runPromise

（来自

effect-runtime.ts

中的

ManagedRuntime

），它包含带有

SentryTracingLive

的

AppLayer

如果无法使用
```
runtime.runPromise
```
（存在循环依赖），代码必须在管道链中添加
```
Effect.provide(SentryTracingLive)
```
测试文件可豁免（它们会提供自己的分层）

搜索模式：

apps/web-app/src/

目录下的

Effect.runPromise(

（排除

__tests__/

）

apps/web-app/src/

目录下的

Effect.runSync(

（排除

__tests__/

）

报告每个匹配项的：

文件路径和行号
是否使用
```
runtime.runPromise
```
（✅）或原生
```
Effect.runPromise
```
（❌）
管道链中是否提供了
```
SentryTracingLive
```
（备选✅）

运行命令：

effect-solutions show services-and-layers

8. Option/Either Internal Tag Anti-Patterns

8. Option/Either内部标签反模式

Check for direct

_tag

branching on

Option

Either

in production code and tests.

Production code: report all direct
```
_tag
```
usage as findings with replacement recommendation
Tests: allow
```
_tag
```
assertions for domain error identity, but flag control-flow branching patterns that should use helpers

Prefer:

```
Either.match
```
,
```
Either.isLeft
```
,
```
Either.isRight
```

Option.match

Option.isSome

Option.isNone

Option.getOrElse

Search patterns to include:

```
if (.*\._tag === "Left")
```
```
if (.*\._tag === "Right")
```
```
if (.*\._tag === "Some")
```
```
if (.*\._tag === "None")
```
```
expect\(.*\._tag\)
```

Run:

effect-solutions show error-handling

检查生产代码和测试中是否直接对

Option

Either

的

_tag

进行分支判断。

生产代码：将所有直接使用
```
_tag
```
的情况作为问题记录，并给出替代方案建议
测试：允许使用
```
_tag
```
断言领域错误的标识，但标记应使用辅助工具的控制流分支模式

推荐使用：

```
Either.match
```
、
```
Either.isLeft
```
、
```
Either.isRight
```

Option.match

、

Option.isSome

、

Option.isNone

、

Option.getOrElse

需包含的搜索模式：

```
if (.*\._tag === "Left")
```
```
if (.*\._tag === "Right")
```
```
if (.*\._tag === "Some")
```
```
if (.*\._tag === "None")
```
```
expect\(.*\._tag\)
```

运行命令：

effect-solutions show error-handling

Output Format

输出格式

Provide a structured report with:

Summary: Overall compliance score (e.g., 7/10)
What's Working Well: List patterns that follow best practices
Improvements Needed: List specific issues with:
- File location
- Current pattern
- Recommended pattern
- Priority (high/medium/low)
- Scope label:
```
production
```
  or
```
test
```
Quick Wins: Easy fixes that can be done immediately
Next Steps: Recommended order of improvements

提供结构化报告，包含：

摘要：整体合规得分（例如：7/10）
合规项：符合最佳实践的模式列表
待改进项：列出具体问题，包含：
- 文件位置
- 当前模式
- 推荐模式
- 优先级（高/中/低）
- 范围标签：
```
production
```
  或
```
test
```
快速修复项：可立即完成的简单修复
后续步骤：推荐的改进顺序

scan-effect-solutions

Original

Translation

Effect Solutions Compliance Audit

Effect Solutions合规审计

Prerequisites

前置条件

Audit Checklist

审计检查清单

1. TypeScript Configuration

1. TypeScript配置

2. Services & Layers Pattern

2. 服务与分层模式

3. Data Modeling

3. 数据建模

4. Error Handling

4. 错误处理

5. Configuration

5. 配置

6. Testing

6. 测试

7. Runtime Usage Anti-Pattern (
`Effect.runPromise`
in Production)

7. 运行时使用反模式（生产环境中的
`Effect.runPromise`
）

8. Option/Either Internal Tag Anti-Patterns

8. Option/Either内部标签反模式

Output Format

输出格式

Related Skills

相关Skill

scan-effect-solutions

Original

Translation

Effect Solutions Compliance Audit

Effect Solutions合规审计

Prerequisites

前置条件

Audit Checklist

审计检查清单

1. TypeScript Configuration

1. TypeScript配置

2. Services & Layers Pattern

2. 服务与分层模式

3. Data Modeling

3. 数据建模

4. Error Handling

4. 错误处理

5. Configuration

5. 配置

6. Testing

6. 测试

7. Runtime Usage Anti-Pattern (Effect.runPromise in Production)

7. 运行时使用反模式（生产环境中的Effect.runPromise）

8. Option/Either Internal Tag Anti-Patterns

8. Option/Either内部标签反模式

Output Format

输出格式

Related Skills

相关Skill

7. Runtime Usage Anti-Pattern (
`Effect.runPromise`
in Production)

7. 运行时使用反模式（生产环境中的
`Effect.runPromise`
）