ag-strict-config-derivation
Enforces Single Source of Truth + Type Derivation pattern for all config lists (columns, permissions, forms, status). Compile-time safety for DTOs and queries.
- License 许可
- MIT
- 最近更新
- 2026-08-02
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- ag-strict-config-derivation
- layer
- helper
- description
- Enforces Single Source of Truth + Type Derivation pattern for all config lists (columns, permissions, forms, status). Compile-time safety for DTOs and queries.
- trigger_keywords
- strict, config, derivation
02 资源文件 3
- 参考文档references/foundational-principles.md3.5 KB
- 参考文档references/single-source-of-truth-pattern.md2.1 KB
- 参考文档references/strict-rules-catalog.md2.8 KB
03 SKILL.md 正文
Strict Config Derivation (Single Source of Truth)
This skill defines the only acceptable pattern for any configuration that controls both runtime behavior and TypeScript types. It is the repository-wide architectural standard for eliminating duplication and drift between queries, DTOs, mappers, and UI.
When to Apply
MUST apply this skill when:
- Defining Drizzle column lists (
columns,.select) - Defining role/permission matrices or navigation visibility
- Defining form field configurations (React Hook Form + Zod)
- Defining status/state machine transitions
- Defining any list of keys used in multiple layers (DB, DTO, UI, validation)
- Refactoring existing
Pick<>or duplicated string unions
Trigger keywords: column list, permission, role matrix, form field, status transition, nav item, feature flag, single source of truth.
How to Use
- Construct the Const: Define your runtime configuration list using
as constto freeze the keys at compile time. - Derive the Type: Map over the keys of the typeof const config (e.g.
[K in keyof typeof CONFIG]) to construct your TypeScript types dynamically. - Consume in Queries and UI: Pass the runtime const directly into database queries and validate return values using
satisfieswith the derived type. - Enforce Clean Comments: Write self-documenting code and only use comments tagged with the Better Comments Tag Dictionary to explain the why of config settings.
Core Rule (Strict)
There must be exactly one source of truth for the list of keys.
Correct Pattern (Mandatory)
export const ORDER_PUBLIC_COLUMNS = {
id: true,
status: true,
totalAmount: true,
createdAt: true,
} as const;
export type OrderPublic = {
[K in keyof typeof ORDER_PUBLIC_COLUMNS]: TOrder[K];
};
const orders = await db.query.orders.findMany({
columns: ORDER_PUBLIC_COLUMNS,
});
return {
id: order.id,
status: order.status,
totalAmount: order.totalAmount,
createdAt: order.createdAt,
} satisfies OrderPublic;
Forbidden Patterns (NEVER)
- Hardcoding column/field lists in multiple files
- Using
Pick<T, "a" | "b" | "c">when a const object already exists - Defining DTO type first, then duplicating keys in the query
- Using
as anyor type assertions to bypass derivation - Manually maintaining three places (query + DTO + mapper)
Coding & Commenting Standards (The Zero Semantic Noise Policy)
All code written in this repository must strictly adhere to commenting standards to ensure readability and eliminate redundant text.
Commenting Rules
- ZERO Semantic Noise: NEVER write comments that explain "WHAT" the code does or translate basic syntax. Clean code must be self-documenting. If the logic is simple, readable, and standard, output ZERO comments.
- Explain "WHY", not "WHAT": Comments MUST ONLY explain complex algorithms, business logic quirks, system constraints, or architectural trade-offs.
- English only: All comments must be written in English.
Better Comments Tag Dictionary
When writing comments, you MUST prefix them with one of the following exactly formatted uppercase tags followed by a colon:
WHY:- Explains the business logic, architectural decisions, or why a specific approach was chosen over another.PERF:- Highlights Big O Time/Space Complexity or performance optimization details.HACK:- Documents workarounds, unconventional solutions, or temporary fixes bypassing system limitations.BUG:- Notes known issues, unexpected behaviors, or failing edge cases.FIXME:- Marks broken, deprecated, or urgently needing refactoring code.TODO:- Indicates planned features, missing implementations, or future improvements.IDEA:- Suggests alternative approaches or architectural improvements for future iterations.INFO:- Crucial contextual info or external documentation links that the developer must know.#region [Name]/#endregion- Logically groups large sections of code/variables to keep files scannable.
Foundational Engineering Principles
This skill also enforces three core principles that support the config derivation pattern:
- YAGNI — You Aren't Gonna Need It: Only implement what current callers actually need. Never add fields, abstraction, or configuration "for the future".
- KISS — Keep It Simple, Stupid: Prefer the simplest, most boring solution. Complexity must be justified by measurable long-term savings.
- DRY — Don't Repeat Yourself: Every piece of knowledge (especially lists of keys) must have exactly one authoritative source.
Detailed definitions and strict MUST/NEVER rules are available in references/foundational-principles.md.
Enforcement
- Any code introducing a new config list without this pattern will be rejected in review.
- AI agents MUST load this skill before writing column, permission, or form configurations.
- Violation is treated as serious architectural debt (equivalent to using
any).
References
04 同仓库更多 Skills
zustand
Rules and standards for state management using Zustand in React and Next.js. Use when implementing client-side stores, persistence with localStorage, or preventing SSR hydration mismatch.
zod
Zod v4 schema validation best practices. Use when defining schemas, utilizing safeParse, or customizing error messages.
upstash-ratelimit
Rules, standards, and references for rate limiting in serverless environments using Upstash Ratelimit. Use when implementing rate limiting, configuring Upstash Redis, or handling request blocking.
ui-design
UI/UX and frontend design best practices guidelines (formerly frontend-design). This skill should be used when writing, reviewing, or designing frontend code to ensure accessibility, performance, and usability. Triggers on tasks involving HTML structure, CSS styling, responsive layouts, form design, animations, or accessibility improvements.
typescript
TypeScript performance, tsconfig, type errors, async patterns — triggered when the user asks to "optimize TypeScript performance", "speed up tsc compilation", "configure tsconfig.json", "fix type errors", "improve async patterns", or encounters TS errors (TS2322, TS2339, "is not assignable to"). Also triggers on .ts, .tsx, .d.ts file work involving type definitions, module organization, or memory management. Does NOT cover TypeScript basics, framework-specific patterns, or testing.
typescript-refactor
TypeScript and TSX refactoring and modernization guidelines from a principal specialist perspective, current to TypeScript 6.0 and React 19. This skill should be used when refactoring, reviewing, or modernizing TypeScript or React/TSX code for type safety, compiler performance, and idiomatic patterns. Triggers on tasks involving type architecture, narrowing, generics, discriminated unions, error handling, React component and hook typing, or migration to modern TypeScript features (satisfies, using, const type parameters, inferred type predicates, isolatedDeclarations, erasable syntax, import attributes).