SkillAtlasSkill 详情

kamae

Kamae (構え) — a stance of readiness.

审核状态：已审核Quality 72Security 90

复制安装命令

用 Codex 或 Claude 安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它先审查 Skill 页面再帮你安装。

复制前请先查看来源、License 和安全提示。

项目 README

来源文件：README.md

抓取于 2026年8月4日

kamae-ts

Documentation →

日本語版: README.ja.md

kamae-ts

Kamae (構え) — a stance of readiness.

An extensible harness of skill plugins for designing and implementing robust server-side TypeScript applications. Each skill encodes a kamae — a practiced stance for a specific design concern — that coding agents apply when generating or reviewing code.

The current stances focus on functional domain modeling; more will be added over time.

Overview of Principles

  • Represent domain state with Discriminated Unions, avoiding classes
  • Define state transitions with pure functions, making invalid transitions compile errors
  • Handle errors as values with Result types (neverthrow / byethrow / fp-ts / option-t), avoiding thrown exceptions
  • Validate external boundaries with schema validation (Zod / Valibot / ArkType), trusting types inside the domain
  • Protect PII at runtime with the Sensitive type

Installation

Via gh skill (the GitHub CLI's agent skills extension):

# Install a single skill (interactive prompt for agent/scope)
gh skill install iwasa-kosui/kamae-ts kamae

# Install non-interactively for Claude Code at user scope
gh skill install iwasa-kosui/kamae-ts kamae \
  --agent claude-code --scope user

# Pin to a specific release
gh skill install iwasa-kosui/kamae-ts kamae@v1.0.0

Or via skills CLI:

npx skills add iwasa-kosui/kamae-ts

Provided Skills

kamae

Triggered when writing server-side TypeScript code (domain models, use cases, repositories, state transitions, error handling, boundary validation, PII protection). Guides code generation through a thin dispatcher SKILL.md that lazy-loads topic sub-files (domain-modeling.md, state-modeling.md, error-handling.md, boundary-defense.md, declarative-style.md, test-data.md) and library-specific guides only when relevant.

kamae-review

Triggered during code review. Walks a checklist of severity-tagged review items (split across checklist/*.md sub-files) and reports findings citing the canonical principle in kamae. Depends on kamae being installed for the knowledge base — install both together.

Customization via Rules

Both skills load applicable rules at the start of each invocation, in priority order:

  1. .claude/rules/*.md (project)
  2. ~/.claude/rules/*.md (user-global)
  3. The plugin's own rules/defaults/*.md

A rule applies to kamae-ts when its frontmatter declares applies-to: kamae, applies-to: kamae-review, or applies-to: "*". Four rule types are supported:

  • library-preference — pin a specific Result or validation library (overrides auto-detection)
  • check-toggle — disable a named review check (e.g., PII protection for projects with no personal data)
  • convention — declare project-specific conventions (e.g., "Branded Types live in src/types/brand.ts")
  • override — replace specific guidance from a topic sub-file

See rules/README.md for the rule format and concrete examples.

For full skill replacement, use Claude Code's standard skill path-shadowing (.claude/skills/kamae/SKILL.md overrides the installed plugin's).

Evaluation

Skill quality is continuously evaluated with microsoft/waza.

Documentation

A reading version of the principles is published at https://iwasa-kosui.github.io/kamae-ts/, in both English (/en/) and Japanese (/ja/).

Community

Join the official Discord server to discuss server-side TypeScript, ask questions, and share what you are working on: https://discord.gg/Z9HVbqEWzd

  • See the community page for channel layout and what kind of conversation happens there.
  • Both this GitHub repository and the Discord server are governed by the Code of Conduct (Contributor Covenant v2.1).

Reference Articles

These principles are based on the following articles:

License

MIT

其他

低风险

  • 来源需自行核对维护者身份。
  • 未检测到明显脚本安装指令。
  • 可能需要外部 token、网络权限或第三方服务。
  • 未检测到高风险命令。
  • 扫描发现：0 条。

Codex — Git Clone 安装

  1. 安装前请先查看来源仓库和风险报告。
  2. 克隆仓库：git clone https://github.com/iwasa-kosui/kamae-ts.git
  3. 将 "skills/kamae" 文件夹复制到 Codex 的 skills 目录中。
  4. 重启 Codex 让新的 skill 生效。

Codex — 手动复制安装

  1. 安装前请先查看来源仓库和风险报告。
  2. 从源仓库下载 SKILL.md 及相关文件。
  3. 在 Codex 的 skills 目录中创建新文件夹。
  4. 将所有 skill 文件复制到新文件夹中。
  5. 重启 Codex 让新的 skill 生效。

Claude Code — Git Clone 安装

  1. 安装前请先查看来源仓库和风险报告。
  2. 克隆仓库：git clone https://github.com/iwasa-kosui/kamae-ts.git
  3. 将 "skills/kamae" 文件夹复制到 Claude Code 的 skills 目录中。
  4. 重启 Claude Code 让新的 skill 生效。

Claude Code — 手动复制安装

  1. 安装前请先查看来源仓库和风险报告。
  2. 从源仓库下载 SKILL.md 及相关文件。
  3. 在 Claude Code 的 skills 目录中创建新文件夹。
  4. 将所有 skill 文件复制到新文件夹中。
  5. 重启 Claude Code 让新的 skill 生效。

Cursor — Git Clone 安装

  1. 安装前请先查看来源仓库和风险报告。
  2. 克隆仓库：git clone https://github.com/iwasa-kosui/kamae-ts.git
  3. 将 "skills/kamae" 文件夹复制到 Cursor 的 skills 目录中。
  4. 重启 Cursor 让新的 skill 生效。

Cursor — 手动复制安装

  1. 安装前请先查看来源仓库和风险报告。
  2. 从源仓库下载 SKILL.md 及相关文件。
  3. 在 Cursor 的 skills 目录中创建新文件夹。
  4. 将所有 skill 文件复制到新文件夹中。
  5. 重启 Cursor 让新的 skill 生效。

GitHub Copilot — Git Clone 安装

  1. 安装前请先查看来源仓库和风险报告。
  2. 克隆仓库：git clone https://github.com/iwasa-kosui/kamae-ts.git
  3. 将 "skills/kamae" 文件夹复制到 GitHub Copilot 的 skills 目录中。
  4. 重启 GitHub Copilot 让新的 skill 生效。

GitHub Copilot — 手动复制安装

  1. 安装前请先查看来源仓库和风险报告。
  2. 从源仓库下载 SKILL.md 及相关文件。
  3. 在 GitHub Copilot 的 skills 目录中创建新文件夹。
  4. 将所有 skill 文件复制到新文件夹中。
  5. 重启 GitHub Copilot 让新的 skill 生效。

Windsurf — Git Clone 安装

  1. 安装前请先查看来源仓库和风险报告。
  2. 克隆仓库：git clone https://github.com/iwasa-kosui/kamae-ts.git
  3. 将 "skills/kamae" 文件夹复制到 Windsurf 的 skills 目录中。
  4. 重启 Windsurf 让新的 skill 生效。

Windsurf — 手动复制安装

  1. 安装前请先查看来源仓库和风险报告。
  2. 从源仓库下载 SKILL.md 及相关文件。
  3. 在 Windsurf 的 skills 目录中创建新文件夹。
  4. 将所有 skill 文件复制到新文件夹中。
  5. 重启 Windsurf 让新的 skill 生效。
查看 SKILL.md 原文
name: kamae
description: |
  Kamae (構え) — robust server-side TypeScript design. Functional domain modeling with
  discriminated unions, pure state transitions, Result types, schema-validated boundaries,
  and PII protection.

  TRIGGER when: writing TypeScript domain models, use cases, repositories, state transitions,
  error handling, boundary validation, or PII handling on the server side; designing types
  for business logic; implementing entity/value-object semantics in TS.
  SKIP: frontend React/Vue components, browser code, build tooling, code generation scripts,
  pure infrastructure-as-code; code unrelated to domain logic.
license: MIT

Kamae — Functional Domain Modeling in TypeScript

Six topic files cover the principles. Read only the file(s) relevant to the current task. The library guides under result-libraries/ and validation-libraries/ are read on demand based on the project's package.json.

Step 0: Load applicable rules

Before any other step, glob and Read rules in priority order:

  1. .claude/rules/*.md (project-level overrides at the working-tree root)
  2. ~/.claude/rules/*.md (user-global preferences)
  3. ../../rules/defaults/*.md relative to this SKILL.md (plugin defaults)

For each file:

  • Read the YAML frontmatter. Skip the rule unless applies-to is kamae or *.
  • Group by name. For each name, keep only the highest-tier instance (1 > 2 > 3); within a tier the lexicographically last filename wins.
  • Apply the body of each surviving rule throughout the remaining steps. A library-preference rule overrides Step 1 detection; a convention rule shapes generated code; an override rule replaces guidance from a specific topic file.

If no rules are found, proceed with the plugin defaults already documented in ../../rules/defaults/.

See ../../rules/README.md for the rule format.

Step 1: Detect project libraries

Read package.json once. Note which Result library and validation library are present:

  • Result libraries — match the first present in priority neverthrow > byethrow > fp-ts > option-t. Load the matching guide under result-libraries/ when error-handling is in scope.
  • Validation libraries — match the first present in priority zod > valibot > arktype. Load the matching guide under validation-libraries/ when boundary or branded-type work is in scope.

If none are present, ask the user before proceeding.

Step 2: Apply the topic relevant to the task

Each topic below is one file. Read it lazily — only the file(s) you need for the current task.

Type-Driven Domain Modeling — domain-modeling.md

Represent states with discriminated unions using kind as the unified discriminant. Use type (not interface), Companion Object pattern, branded types via the project's validation library, Readonly<>, function property notation, and one-concept-per-file structure.

State Transitions — state-modeling.md

Express transitions with pure functions. Argument types constrain valid source states; return types make targets explicit. Invalid transitions become compile errors. Use assertNever for exhaustiveness.

Error Handling — error-handling.md

Treat errors as values via Result. Define error types as discriminated unions so callers branch exhaustively. Do not throw exceptions in domain code.

Boundary Defense — boundary-defense.md

Validate every external input (API requests, DB results, file/queue/env) with a schema at runtime. Trust types inside the domain. Do not use type assertions — as const and as const satisfies Type are the only allowed forms; when the type is unknown, parse through a validation-library schema instead. Apply Sensitive<T> to PII fields; the validation schema auto-wraps them.

Declarative Style — declarative-style.md

Use filter / map / reduce with companion-object predicates instead of imperative loops. Model domain events as immutable records.

Test Data — test-data.md

Define fixtures with as const satisfies Type to preserve discriminant literal types and prevent widening.

Examples

Worked end-to-end examples are in examples/. Read them only when the topic guide cites a specific example.

Applying These Principles

These are recommendations, not strict rules. Use judgment based on context. If you deviate from a principle, state the reason in a comment. Justifiable reasons include: external library requires class inheritance, immutable object creation cost is a measured performance concern, or a different pattern has been adopted by team agreement.

发现问题？提交给管理员复核

评分：

评论 (0)

暂无评论，成为第一个评论者吧！