From 33b0b2bb40a380b57d8fbf5015e1f08876c29d3f Mon Sep 17 00:00:00 2001 From: roottool Date: Sun, 15 Feb 2026 14:36:38 +0900 Subject: [PATCH 1/7] docs: refactor CLAUDE.md to eliminate AGENTS.md duplication and add dev tooling info Remove content duplicated with AGENTS.md/README.md (coverage lists, API docs, type definitions, JSDoc details, architecture notes) and add missing development information (toolchain table, lint/format commands, CI/CD workflow locations). Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 166 ++++++++++++++++++------------------------------------ 1 file changed, 54 insertions(+), 112 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8bf2a2b..d63b78e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,20 +1,10 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -**safe-formdata** is a boundary-focused FormData parser that establishes a strict, security-oriented boundary between untrusted FormData input and application logic. +**safe-formdata** is a boundary-focused FormData parser — Claude Code向けの作業指示書。 ## Critical: Follow AGENTS.md -**All implementation and review decisions must strictly adhere to AGENTS.md**, which defines the non-negotiable technical rules: - -- Implementation-level interpretation of README.md design principles -- Security implementation rules (prototype safety, forbidden keys) -- API contract and type definitions -- Non-goals (hard exclusions for any feature requests) -- Code review criteria ("Review rule of thumb") +**All implementation and review decisions must strictly adhere to AGENTS.md.** When implementing features or reviewing code: @@ -22,23 +12,12 @@ When implementing features or reviewing code: 2. Then, apply AGENTS.md technical constraints 3. If a change makes the parser smarter/more convenient, it likely violates the boundary → reject it -## Project Skills +## Agent Skills -This project includes **Agent Skills** in the `skills/` directory, providing automated code review capabilities for Claude Code. +The `boundary-validator` skill (`skills/boundary-validator/`) validates code changes against AGENTS.md design rules. -### boundary-validator - -The `boundary-validator` skill automatically validates code changes against AGENTS.md design rules: - -- **Location**: `skills/boundary-validator/` -- **Purpose**: Detect boundary principle violations during PR creation and code review - **Triggers**: Automatically activates when creating PRs or requesting code reviews -- **Coverage**: - - Keys are opaque strings (no bracket/dot notation parsing) - - No silent behavior (detect duplicate keys) - - No inference, no convenience (no type coercion, validation) - - Explicit issue reporting (no exceptions for input errors) - - Security rules (forbidden keys, prototype safety) +- **Coverage**: See AGENTS.md "Agent Skills" section for the full coverage list **Usage in Claude Code**: @@ -46,43 +25,6 @@ The `boundary-validator` skill automatically validates code changes against AGEN Review this code against boundary-validator rules ``` -The skill will automatically check your implementation for violations and provide specific feedback with line references. - -### For Non-Claude Code Tools - -If you're using other development tools (Windsurf, Cursor, etc.): - -- **Reference AGENTS.md directly** in your prompts or tool configuration -- Agent Skills are primarily designed for Claude Code -- See `skills/README.md` for more details on cross-tool compatibility - -For complete information about the skills system, see [`skills/README.md`](skills/README.md) and [`AGENTS.md`](AGENTS.md#agent-skills). - -## API Documentation - -For complete API documentation, TypeScript interfaces, and usage examples, see **README.md**. - -**README.md follows a "philosophy-first" structure:** - -1. **Overview** - What this library is and is not -2. **Design principles** - Core philosophy (keys are opaque, no silent fixes, etc.) -3. **Security scope** - What's in scope vs out of scope -4. **Design decisions (Why not?)** - Why common features are intentionally omitted -5. **Installation** - Package manager setup -6. **Quick Start** - Minimal working example -7. **API** - Detailed API reference - -This structure ensures users understand the "boundary-focused" philosophy before writing code, reducing misuse. - -Key resources: - -- API interfaces (ParseResult discriminated union, ParseIssue) -- Issue codes (invalid_key, forbidden_key, duplicate_key) -- Security scope (in scope vs out of scope) -- Design decisions (Why no structural inference?, etc.) -- Type narrowing pattern (`data !== null`) -- Versioning policy - ## Usage Examples The `examples/` directory contains comprehensive usage examples: @@ -99,6 +41,20 @@ Run type checking for examples: bun run check:type:example ``` +## Toolchain + +| Tool | Role | +| ---------------------- | ------------------------------- | +| **bun** | Package manager / script runner | +| **TypeScript** (`tsc`) | Type checking | +| **tsup** | Build (bundler) | +| **vitest** | Test runner | +| **oxlint** | Linter | +| **Biome** | Formatter (TS/JS/JSON) | +| **Prettier** | Formatter (Markdown/YAML) | +| **publint** / **attw** | Package export validation | +| **npm-run-all2** | Script orchestration | + ## Development Commands ### Setup @@ -114,78 +70,64 @@ bun run dev # Watch mode for building bun run test:watch # Watch mode for testing ``` -### Testing +### Linting & Formatting ```bash -bun run test # Run all tests -bun run test:coverage # Run tests with coverage report +bun run lint # oxlint (deny-warnings) +bun run lint:fix # oxlint --fix-suggestions +bun run format # Biome + Prettier (write) +bun run fix # lint:fix + format (all-in-one auto-fix) ``` -### Build +### Quality Checks ```bash -bun run build # Build for production -bun run check:type:source # TypeScript type checking +bun run check # lint + format check (read-only) +bun run check:type # TypeScript check (source + examples) +bun run check:type:source # TypeScript check (source only) +bun run check:type:example # TypeScript check (examples only) +bun run check:package # publint + attw export validation ``` -## Type Safety and IDE Integration - -All type definitions include comprehensive JSDoc comments for enhanced IDE experience: - -### Type Narrowing Pattern +### Testing -The `ParseResult` type is a discriminated union. Use `data !== null` to narrow the type: +```bash +bun run test # Run all tests +bun run test:coverage # Run tests with coverage report +``` -```typescript -const result = parse(formData); +### Build -if (result.data !== null) { - // TypeScript knows: data is Record - // TypeScript knows: issues is [] - console.log(result.data.username); -} else { - // TypeScript knows: data is null - // TypeScript knows: issues is ParseIssue[] - console.error(result.issues); -} +```bash +bun run build # Build for production (tsup) ``` -### JSDoc Benefits +### Publishing -When you hover over types in your IDE, you'll see: - -- **ParseResult** - Discriminated union explanation and usage examples -- **ParseIssue** - Each property's purpose and security implications -- **IssueCode** - Security rationale for each issue code +```bash +bun run prepare:publish # Full pre-publish pipeline: type check → test:coverage → build → check:package +``` -Example JSDoc locations: +## CI/CD -- `src/types/ParseResult.ts` - Full discriminated union documentation -- `src/types/ParseIssue.ts` - Property-level explanations -- `src/types/IssueCode.ts` - Security-focused code definitions +- **Workflows**: `.github/workflows/` + - `ci.yml` - Main CI pipeline + - `publish.yml` - npm publish + - `prepare-release-pr.yml` - Release PR automation + - `wc-*.yml` - Reusable workflow components (type-check, lint-format, test, etc.) +- **PR template**: `.github/PULL_REQUEST_TEMPLATE.md` +- **Renovate**: `.github/renovate.json` -### Important: No `.ok` Property +## Important: No `.ok` Property -Unlike some libraries, `ParseResult` does not have a `.ok` property. Use `data !== null` instead: +`ParseResult` does not have a `.ok` property. Use `data !== null` to narrow the type: ```typescript -// ✅ Correct +// Correct if (result.data !== null) { } -// ❌ Wrong - .ok does not exist +// Wrong - .ok does not exist if (result.ok) { } ``` - ---- - -## Architecture Notes - -This project follows a minimal, security-focused architecture: - -- **TypeScript-based**: Strict type checking enabled -- **Minimal dependencies**: Zero runtime dependencies, minimal dev dependencies -- **Framework-agnostic**: Works with any JavaScript framework or runtime -- **Security-first**: Uses `Object.create(null)` to prevent prototype pollution -- **Discriminated unions**: Type-safe result handling without boolean flags From 99009b4eb192623bf611c1392db2ef64b6ee3036 Mon Sep 17 00:00:00 2001 From: roottool Date: Sun, 15 Feb 2026 14:38:07 +0900 Subject: [PATCH 2/7] docs: add language specifier to fenced code block in CLAUDE.md Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index d63b78e..54bf536 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,7 +21,7 @@ The `boundary-validator` skill (`skills/boundary-validator/`) validates code cha **Usage in Claude Code**: -``` +```text Review this code against boundary-validator rules ``` From 1dc0de42fd97c27ec949b1a76c5b0b797dc18328 Mon Sep 17 00:00:00 2001 From: roottool Date: Sun, 15 Feb 2026 14:39:14 +0900 Subject: [PATCH 3/7] docs: fix duplicate heading in AGENTS.md (MD024) Rename "Purpose" under Agent Skills to "What are Agent Skills?" to avoid duplicate heading with the top-level "Purpose" section. Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 1ac2bdc..46294b7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -249,7 +249,7 @@ When in doubt, reject the change. This project provides the content of AGENTS.md in Agent Skills format through the `skills/` directory. -### Purpose +### What are Agent Skills? Agent Skills are structured knowledge packages optimized for Claude Code and similar AI-powered development tools. They enable: From 843e97b324e5caab4db51cf25ba5e48ea9045398 Mon Sep 17 00:00:00 2001 From: roottool Date: Sun, 15 Feb 2026 14:45:10 +0900 Subject: [PATCH 4/7] docs: remove redundant project overview from CLAUDE.md The project description already exists in README.md and AGENTS.md. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 54bf536..35f3675 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,5 @@ # CLAUDE.md -**safe-formdata** is a boundary-focused FormData parser — Claude Code向けの作業指示書。 - ## Critical: Follow AGENTS.md **All implementation and review decisions must strictly adhere to AGENTS.md.** From f26d3ccacc1207d733221b097171c2d0bc50b6db Mon Sep 17 00:00:00 2001 From: roottool Date: Sun, 15 Feb 2026 14:48:21 +0900 Subject: [PATCH 5/7] docs: remove "Using Skills in Other Tools" section from AGENTS.md Tool compatibility tables belong in each tool's own documentation, not in the project's design rules document. This avoids staleness and keeps AGENTS.md focused on implementation rules. Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 46294b7..c6c8d9f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -276,19 +276,6 @@ Validates code changes against the Design rules and Security rules defined in th For details, see [`skills/boundary-validator/SKILL.md`](skills/boundary-validator/SKILL.md). -### Using Skills in Other Tools - -Agent Skills are currently supported primarily by Claude Code. For other development tools: - -| Tool | Support | Usage | -| ----------------- | --------- | -------------------------------------------- | -| **Claude Code** | ✅ Full | Automatic detection of `skills/` directory | -| **Windsurf** | ⚠️ Manual | Reference this AGENTS.md directly in prompts | -| **Cursor** | ⚠️ Manual | Use `.cursorrules` or reference AGENTS.md | -| **claude.ai Web** | ⚠️ Manual | Upload SKILL.md as project knowledge | - -**For non-supported tools**: Use this AGENTS.md document directly, or configure your tool to reference the project's design principles explicitly in CLAUDE.md. - ### Relationship to AGENTS.md - **AGENTS.md is the source of truth**: All design principle changes are made here first From 0ff315c9be9749ebd6503954d2af159d72d6b87b Mon Sep 17 00:00:00 2001 From: roottool Date: Sun, 15 Feb 2026 14:51:53 +0900 Subject: [PATCH 6/7] docs: remove non-rule sections from AGENTS.md, move maintenance to skills/ Remove sections that are not implementation rules: - Security guarantees (pointer-only, zero original content) - v0.1.0 scope (frozen historical info) - Versioning (pointer-only) - Agent Skills (infrastructure/maintenance, not design rules) Move detailed maintenance steps to skills/README.md where they belong. Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 85 ------------------------------------------------ skills/README.md | 12 +++++-- 2 files changed, 9 insertions(+), 88 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c6c8d9f..d06b66c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -95,14 +95,6 @@ This is non-optional and part of the boundary definition. --- -## Security guarantees - -> **Note**: For security scope definitions, see **README.md Security scope section**. - -For implementation-level security constraints, see the **Security rules (mandatory) section** above. - ---- - ## Key validation criteria To maintain a predictable boundary, keys must meet the following criteria. Failure to do so results in an `invalid_key` issue. @@ -214,23 +206,6 @@ If a feature conflicts with these, it must be rejected. --- -## v0.1.0 scope - -v0.1.0 establishes the FormData boundary with: - -- Flat FormData parsing into a plain JavaScript object -- Detection of forbidden, duplicate, and invalid keys -- Non-throwing issue reporting -- A minimal, stable public API - ---- - -## Versioning - -For versioning policy details, see **README.md Versioning section**. - ---- - ## Review rule of thumb If a change makes the parser: @@ -242,63 +217,3 @@ If a change makes the parser: it likely violates the boundary. When in doubt, reject the change. - ---- - -## Agent Skills - -This project provides the content of AGENTS.md in Agent Skills format through the `skills/` directory. - -### What are Agent Skills? - -Agent Skills are structured knowledge packages optimized for Claude Code and similar AI-powered development tools. They enable: - -- **Automatic triggering**: Skills activate during PR creation, code review, etc. -- **Progressive disclosure**: Load only necessary information on demand -- **Standardized format**: Follows [agentskills.dev](https://agentskills.dev) specification - -### Available Skills - -#### boundary-validator (`skills/boundary-validator/`) - -Validates code changes against the Design rules and Security rules defined in this document. - -- **Purpose**: Automated detection of boundary principle violations -- **Triggers**: PR creation, code review, post-implementation checks -- **Coverage**: - - Keys are opaque strings (no bracket/dot notation parsing) - - No silent behavior (detect duplicate keys) - - No inference, no convenience (no type coercion, validation) - - Explicit issue reporting (no exceptions for input errors) - - Security rules (forbidden keys, prototype safety) - -**Supported tools**: Claude Code - -For details, see [`skills/boundary-validator/SKILL.md`](skills/boundary-validator/SKILL.md). - -### Relationship to AGENTS.md - -- **AGENTS.md is the source of truth**: All design principle changes are made here first -- **Skills are optimized versions**: The `skills/` directory provides the same rules in a format optimized for agent consumption -- **Synchronization**: When AGENTS.md is updated, corresponding files in `skills/boundary-validator/references/` should be updated - -This is a **strategic duplication**: - -- **AGENTS.md**: Human-readable, comprehensive, works with all tools -- **skills/**: Agent-optimized, progressive disclosure, auto-triggering (Claude Code) - -Both serve different audiences and purposes, making the duplication necessary for maximum compatibility. - -### Maintenance - -When updating design rules: - -1. **Edit AGENTS.md first** (this file is the master) -2. **Update corresponding references** in `skills/boundary-validator/references/` - - `design-rules.md` - Lines 36-75 of this file - - `security-rules.md` - Lines 76-95 of this file - - `api-contract.md` - Lines 119-199 of this file -3. **Increment skill version** in `skills/boundary-validator/SKILL.md` frontmatter -4. **Commit both** AGENTS.md and skills/ changes together - -For more information about the skills system, see [`skills/README.md`](skills/README.md). diff --git a/skills/README.md b/skills/README.md index 902e138..406fb30 100644 --- a/skills/README.md +++ b/skills/README.md @@ -47,9 +47,15 @@ If you're using tools that don't support Agent Skills, please reference [AGENTS. ## Maintenance Policy -1. **AGENTS.md is the source of truth**: Make design principle changes in AGENTS.md first -2. **Skills follow**: Reflect AGENTS.md changes in `skills/` -3. **Strategic duplication**: Document duplication is acceptable due to different purposes +When updating design rules: + +1. **Edit AGENTS.md first** (source of truth) +2. **Update corresponding references** in `boundary-validator/references/` + - `design-rules.md` — Design rules section + - `security-rules.md` — Security rules section + - `api-contract.md` — API contract section +3. **Increment skill version** in `boundary-validator/SKILL.md` frontmatter +4. **Commit both** AGENTS.md and `skills/` changes together ## Official Specification From 3beb602b7e7a879240ab087366640f120c61d429 Mon Sep 17 00:00:00 2001 From: roottool Date: Sun, 15 Feb 2026 14:54:20 +0900 Subject: [PATCH 7/7] docs: remove stale sections from skills/README.md, fix broken reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove Supported Tools and Relationship to AGENTS.md sections from skills/README.md (staleness-prone, redundant with Maintenance Policy). Fix CLAUDE.md broken reference to deleted AGENTS.md "Agent Skills" section — now points to "Design rules" and "Security rules". Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 2 +- skills/README.md | 19 ------------------- 2 files changed, 1 insertion(+), 20 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 35f3675..6650560 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,7 +15,7 @@ When implementing features or reviewing code: The `boundary-validator` skill (`skills/boundary-validator/`) validates code changes against AGENTS.md design rules. - **Triggers**: Automatically activates when creating PRs or requesting code reviews -- **Coverage**: See AGENTS.md "Agent Skills" section for the full coverage list +- **Coverage**: See AGENTS.md "Design rules" and "Security rules" sections **Usage in Claude Code**: diff --git a/skills/README.md b/skills/README.md index 406fb30..13d35cd 100644 --- a/skills/README.md +++ b/skills/README.md @@ -26,25 +26,6 @@ Performs code review based on boundary principles. For details, see [`boundary-validator/SKILL.md`](./boundary-validator/SKILL.md). -## Supported Tools - -### ✅ Automatic Support - -- **Claude Code** - Automatically detects `skills/` in the project - -### ⚠️ Manual Reference Required - -- **Windsurf** - Instruct to reference AGENTS.md directly -- **Cursor** - Specify rules in AGENTS.md or `.cursorrules` -- **claude.ai Web** - Manually upload as project knowledge - -## Relationship to AGENTS.md - -- **AGENTS.md**: Master document for both humans and agents -- **skills/**: Optimized version for Agent Skills-compatible tools - -If you're using tools that don't support Agent Skills, please reference [AGENTS.md](../AGENTS.md) directly. - ## Maintenance Policy When updating design rules: