Agent Skills
› NeverSight/learn-skills.dev
› backend-refactor-quality-gate
backend-refactor-quality-gate
GitHubFintrack.Server后端重构质量门禁，验证领域封装、CQRS布局、Result模式及测试等。适用于涉及多层变更或对齐Budget规范的重构任务，确保代码一致性。
Trigger Scenarios
重构聚合根（如Guid迁移）
重组Application命令/查询
使功能对齐既定模式（如Budgets）
涉及ID、仓储、迁移或多层后端变更
Install
npx skills add NeverSight/learn-skills.dev --skill backend-refactor-quality-gate -g -y
SKILL.md
Frontmatter
{
"name": "backend-refactor-quality-gate",
"description": "Quality gate for Fintrack.Server backend refactors in CeroBase: verify domain encapsulation, CQRS folder layout, Result-based application messaging, FluentValidation, EF migrations, API consistency, and mandatory tests before marking work complete. Use whenever refactoring aggregates (e.g. Guid migrations), restructuring Application commands\/queries, aligning a feature with an established pattern such as Budgets, or any multi-layer backend change where \"quick fixes\" would leave the codebase inconsistent—load this skill first, then open only the referenced skill files needed for the task rather than duplicating their text."
}
Backend refactor quality gate (Fintrack.Server)
This skill does not restate other skills. It defines what “done” means for a backend refactor and which skills to read to implement it correctly.
When to use
- You are changing Domain, Application, Infrastructure, API, or database shape together.
- You are making a feature consistent with an existing exemplar (in this repo,
Budget/ Budgets are the default reference for CQRS +Result+ folder layout). - You touched IDs, repositories, migrations, handlers, or controllers and need a single checklist so nothing is forgotten.
In-repo reference (concrete layout)
Use Application/Budgets/ as the pattern for:
- One folder per command or query under
Commands/<UseCase>/andQueries/<UseCase>/. ICommand/ICommand<T>/IQuery<T>with handlers returningResult/Result<T>(see messaging underFintrack.Server/Application/Abstractions/Messaging/).- Co-located FluentValidation
*Validatortypes. ApiControllerBase+HandleResult/HandleFailurein API projects (seeFintrack.Server/Api/Controllers/ApiControllerBase.cs).
Use Domain/Budgets/Budget.cs as the pattern for a rich aggregate when that is the target (factory, private setters, domain events, RegisterDeletion where applicable).
Completion checklist (must all be true before “done”)
Work through the list; for each row, open the linked skill and apply it—do not invent parallel conventions.
1. Intent and scope
- If the change is new behavior or ambiguous design, use
brainstorming(.agents/skills/brainstorming/SKILL.md) before coding.
2. Domain layer
- Entities, factories, invariants, encapsulation:
.agents/skills/domain-entity-generator/SKILL.md Result/Errorfor domain rules (not thrown exceptions for business failures in the domain):.agents/skills/result-pattern/SKILL.md- Domain events (if the aggregate should raise them):
.agents/skills/domain-events-generator/SKILL.md- If you adopt outbox-style dispatch, follow
.agents/skills/outbox-pattern/SKILL.mdas already wired in this solution; do not fork a second pattern.
- If you adopt outbox-style dispatch, follow
- Aggregate persistence port: repository interface stays with the aggregate under
Fintrack.Server/Domain/...per.agents/skills/dotnet-clean-architecture/SKILL.md(Critical Rules + repository placement).
3. Application layer
- Folder layout (one use case per leaf folder, grouped under
Commands//Queries/):.agents/skills/dotnet-clean-architecture/SKILL.md(Application{Feature}folder layout). - Commands/queries detail:
.agents/skills/cqrs-command-generator/SKILL.md,.agents/skills/cqrs-query-generator/SKILL.md - Validators:
.agents/skills/fluent-validation/SKILL.md - Cross-cutting MediatR behaviors (if adding pipeline concerns):
.agents/skills/pipeline-behaviors/SKILL.md
4. Infrastructure
- Repository implementations:
.agents/skills/repository-pattern/SKILL.md - EF mappings / constraints / relationships:
.agents/skills/ef-core-configuration/SKILL.md - Postgres/migration safety for non-trivial type changes:
.agents/skills/supabase-postgres-best-practices/SKILL.md(when writing raw SQL or tricky migrations)
5. API
- Controller shape, MediatR, authorization:
.agents/skills/api-controller-generator/SKILL.md,.agents/skills/permission-authorization/SKILL.md - Prefer
Resultend-to-end from handler to controller for commands/queries that already returnResult, matchingBudgetsController+ApiControllerBase.
6. Testing (mandatory — the refactor is NOT done until every layer is covered)
Placement rules: unit tests only in Fintrack.Tests/, integration tests only in Fintrack.IntegrationTests/ — never inside Fintrack.Server/. See AGENTS.md.
Open each skill below and follow its completion checklist for the feature being refactored. Do not silently skip any layer — if a layer does not apply, acknowledge it explicitly.
- Unit tests (all layers):
.agents/skills/unit-testing/SKILL.md— see the "Per-layer completion checklist" section. Covers:- Domain entity / aggregate tests
- Command handler tests
- Query handler tests
- Validator tests
- Repository tests (EF Core InMemory)
- API controller unit tests (mock ISender)
- Integration tests (CRUD + authorization):
.agents/skills/integration-testing/SKILL.md— see the "CeroBase monorepo completion checklist" section. Covers:- Functional CRUD tests (create, get, update, delete, user isolation)
- Authorization tests (401, 403, read-only role)
- Integration-test roles in
Roles.cs/RolePermissions.cs
- Green bar:
dotnet testpasses for bothFintrack.TestsandFintrack.IntegrationTestsbefore claiming completion.
7. Persistence and data rollout
- If schema changed: add an EF migration, update snapshot, and document any unsafe
Down(if used) for operators. - Reseed or migration notes follow existing
DefaultCategorySeeder/ migration patterns—no ad hoc one-off scripts unless the task explicitly requires them.
8. Git
- Commit with Conventional Commits:
.agents/skills/conventional-commit/SKILL.md - If the API contract changes (route shape, id type, status codes), mark breaking changes in the commit footer when appropriate.
Explicit anti-patterns (fail the gate)
- Multiple unrelated use cases in the same leaf Application folder (flat
Commands/orQueries/dumping ground). - Handlers that throw for normal business outcomes when
Resultis the established pattern for that feature area. - Business logic left in controllers instead of MediatR handlers.
- Tests added under
Fintrack.Server/(forbidden). - Domain types referencing Application or Infrastructure.
After the refactor
Offer to run description optimization only if this gate skill is installed in a Claude Code environment with the skill-creator scripts; see .agents/skills/skill-creator/SKILL.md (“Description Optimization”). For day-to-day refactors, completing the checklist is sufficient.
Version History
- e0220ca Current 2026-07-05 23:30
