agent-bot/takt
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

takt: # タスク指示書: 専門知識のknowledgeへの抽出と付与

Browse Source 
## 概要
既存のスタンス/インストラクションに埋め込まれているフロントエンド・バックエンド等の専門知識をknowledgeファイルとして抽出し、抽出元に適切に付与する。

---

## タスク

### 1. 専門知識の抽出（優先度: 高）

既存のスタンス・インストラクションファイルをレビューし、以下の専門知識を特定・抽出：
- **フロントエンド知識**（React、CSS、UI/UXなど）
- **バックエンド知識**（API設計、DB、サーバーサイドなど）
- **その他の専門知識**（発見したもの）

抽出した知識をknowledgeファイルとして作成する。

### 2. 抽出元への付与（優先度: 高）

抽出した知識を、元々その知識を使用していたスタンス/インストラクションに付与設定する。
- 抽出元 = 付与先

---

## 確認方法
- 抽出後、元のスタンス/インストラクションから専門知識が分離されていること
- 抽出元にknowledgeが正しく付与設定されていること
This commit is contained in:
nrslib 2026-02-07 13:01:15 +09:00
parent e7d5dbfb33
commit b7c2a4db08
24 changed files with 3050 additions and 2733 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
resources/global/en/knowledge/.gitkeep
View File

427
resources/global/en/knowledge/architecture.md Normal file
View File

@ -0,0 +1,427 @@
# Architecture Knowledge
## Structure & Design
**File Organization:**
| Criteria | Judgment |
|----------|----------|
| Single file > 200 lines | Consider splitting |
| Single file > 300 lines | REJECT |
| Single file with multiple responsibilities | REJECT |
| Unrelated code coexisting | REJECT |
**Module Structure:**
- High cohesion: Related functionality grouped together
- Low coupling: Minimal inter-module dependencies
- No circular dependencies
- Appropriate directory hierarchy
**Function Design:**
- One responsibility per function
- Consider splitting functions over 30 lines
- Side effects clearly defined
**Layer Design:**
- Dependency direction: Upper layers -> Lower layers (reverse prohibited)
- Controller -> Service -> Repository flow maintained
- 1 interface = 1 responsibility (no giant Service classes)
**Directory Structure:**
Structure pattern selection:
| Pattern | Use Case | Example |
|---------|----------|---------|
| Layered | Small scale, CRUD-centric | `controllers/`, `services/`, `repositories/` |
| Vertical Slice | Medium-large scale, high feature independence | `features/auth/`, `features/order/` |
| Hybrid | Common foundation + feature modules | `core/` + `features/` |
Vertical Slice Architecture (organizing code by feature):
```
src/
├── features/
│ ├── auth/
│ │ ├── LoginCommand.ts
│ │ ├── LoginHandler.ts
│ │ ├── AuthRepository.ts
│ │ └── auth.test.ts
│ └── order/
│ ├── CreateOrderCommand.ts
│ ├── CreateOrderHandler.ts
│ └── ...
└── shared/ # Shared across features
├── database/
└── middleware/
```
Vertical Slice criteria:
| Criteria | Judgment |
|----------|----------|
| Single feature spans 3+ layers | Consider slicing |
| Minimal inter-feature dependencies | Recommend slicing |
| Over 50% shared processing | Keep layered |
| Team organized by features | Slicing required |
Prohibited patterns:
| Pattern | Problem |
|---------|---------|
| Bloated `utils/` | Becomes graveyard of unclear responsibilities |
| Lazy placement in `common/` | Dependencies become unclear |
| Excessive nesting (4+ levels) | Navigation difficulty |
| Mixed features and layers | `features/services/` prohibited |
**Separation of Concerns:**
- Read and write responsibilities separated
- Data fetching at root (View/Controller), passed to children
- Error handling centralized (no try-catch scattered everywhere)
- Business logic not leaking into Controller/View
## Code Quality Detection
**Explanatory Comment (What/How) Detection Criteria:**
Detect comments that simply restate code behavior in natural language.
| Judgment | Criteria |
|----------|----------|
| REJECT | Restates code behavior in natural language |
| REJECT | Repeats what is already obvious from function/variable names |
| REJECT | JSDoc that only paraphrases the function name without adding information |
| OK | Explains why a particular implementation was chosen |
| OK | Explains the reason behind seemingly unusual behavior |
| Best | No comment needed — the code itself communicates intent |
```typescript
// REJECT - Restates code (What)
// If interrupted, abort immediately
if (status === 'interrupted') {
return ABORT_STEP;
}
// REJECT - Restates the loop
// Check transitions in order
for (const transition of step.transitions) {
// REJECT - Repeats the function name
/** Check if status matches transition condition. */
export function matchesCondition(status: Status, condition: TransitionCondition): boolean {
// OK - Design decision (Why)
// User interruption takes priority over piece-defined transitions
if (status === 'interrupted') {
return ABORT_STEP;
}
// OK - Reason behind seemingly odd behavior
// stay can cause loops, but is only used when explicitly specified by the user
return step.name;
```
**Direct State Mutation Detection Criteria:**
Detect direct mutation of arrays or objects.
```typescript
// REJECT - Direct array mutation
const steps: Step[] = getSteps();
steps.push(newStep); // Mutates original array
steps.splice(index, 1); // Mutates original array
steps[0].status = 'done'; // Nested object also mutated directly
// OK - Immutable operations
const withNew = [...steps, newStep];
const without = steps.filter((_, i) => i !== index);
const updated = steps.map((s, i) =>
i === 0 ? { ...s, status: 'done' } : s
);
// REJECT - Direct object mutation
function updateConfig(config: Config) {
config.logLevel = 'debug'; // Mutates argument directly
config.steps.push(newStep); // Nested mutation too
return config;
}
// OK - Returns new object
function updateConfig(config: Config): Config {
return {
...config,
logLevel: 'debug',
steps: [...config.steps, newStep],
};
}
```
## Security (Basic Checks)
- Injection prevention (SQL, Command, XSS)
- User input validation
- Hardcoded sensitive information
## Testability
- Dependency injection enabled
- Mockable design
- Tests are written
## Anti-Pattern Detection
REJECT when these patterns are found:
| Anti-Pattern | Problem |
|--------------|---------|
| God Class/Component | Single class with too many responsibilities |
| Feature Envy | Frequently accessing other modules' data |
| Shotgun Surgery | Single change ripples across multiple files |
| Over-generalization | Variants and extension points not currently needed |
| Hidden Dependencies | Child components implicitly calling APIs etc. |
| Non-idiomatic | Custom implementation ignoring language/FW conventions |
## Abstraction Level Evaluation
**Conditional Branch Proliferation Detection:**
| Pattern | Judgment |
|---------|----------|
| Same if-else pattern in 3+ places | Abstract with polymorphism → REJECT |
| switch/case with 5+ branches | Consider Strategy/Map pattern |
| Flag arguments changing behavior | Split into separate functions → REJECT |
| Type-based branching (instanceof/typeof) | Replace with polymorphism → REJECT |
| Nested conditionals (3+ levels) | Early return or extract → REJECT |
**Abstraction Level Mismatch Detection:**
| Pattern | Problem | Fix |
|---------|---------|-----|
| Low-level details in high-level processing | Hard to read | Extract details to functions |
| Mixed abstraction levels in one function | Cognitive load | Align to same granularity |
| DB operations mixed with business logic | Responsibility violation | Separate to Repository layer |
| Config values mixed with processing logic | Hard to change | Externalize configuration |
**Good Abstraction Examples:**
```typescript
// Proliferating conditionals
function process(type: string) {
if (type === 'A') { /* process A */ }
else if (type === 'B') { /* process B */ }
else if (type === 'C') { /* process C */ }
// ...continues
}
// Abstract with Map pattern
const processors: Record<string, () => void> = {
A: processA,
B: processB,
C: processC,
};
function process(type: string) {
processors[type]?.();
}
```
```typescript
// Mixed abstraction levels
function createUser(data: UserData) {
// High level: business logic
validateUser(data);
// Low level: DB operation details
const conn = await pool.getConnection();
await conn.query('INSERT INTO users...');
conn.release();
}
// Aligned abstraction levels
function createUser(data: UserData) {
validateUser(data);
await userRepository.save(data); // Details hidden
}
```
## Workaround Detection
Don't overlook compromises made to "just make it work."
| Pattern | Example |
|---------|---------|
| Unnecessary package additions | Mystery libraries added just to make things work |
| Test deletion/skipping | `@Disabled`, `.skip()`, commented out |
| Empty implementations/stubs | `return null`, `// TODO: implement`, `pass` |
| Mock data in production | Hardcoded dummy data |
| Swallowed errors | Empty `catch {}`, `rescue nil` |
| Magic numbers | Unexplained `if (status == 3)` |
## Strict TODO Comment Prohibition
"We'll do it later" never gets done. What's not done now is never done.
TODO comments are immediate REJECT.
```kotlin
// REJECT - Future-looking TODO
// TODO: Add authorization check by facility ID
fun deleteCustomHoliday(@PathVariable id: String) {
deleteCustomHolidayInputPort.execute(input)
}
// APPROVE - Implement now
fun deleteCustomHoliday(@PathVariable id: String) {
val currentUserFacilityId = getCurrentUserFacilityId()
val holiday = findHolidayById(id)
require(holiday.facilityId == currentUserFacilityId) {
"Cannot delete holiday from another facility"
}
deleteCustomHolidayInputPort.execute(input)
}
```
Only acceptable TODO cases:
| Condition | Example | Judgment |
|-----------|---------|----------|
| External dependency prevents implementation + Issued | `// TODO(#123): Implement after API key obtained` | Acceptable |
| Technical constraint prevents + Issued | `// TODO(#456): Waiting for library bug fix` | Acceptable |
| "Future implementation", "add later" | `// TODO: Add validation` | REJECT |
| "No time for now" | `// TODO: Refactor` | REJECT |
Correct handling:
- Needed now → Implement now
- Not needed now → Delete the code
- External blocker → Create issue and include ticket number in comment
## DRY Violation Detection
Detect duplicate code.
| Pattern | Judgment |
|---------|----------|
| Same logic in 3+ places | Immediate REJECT - Extract to function/method |
| Same validation in 2+ places | Immediate REJECT - Extract to validator function |
| Similar components 3+ | Immediate REJECT - Create shared component |
| Copy-paste derived code | Immediate REJECT - Parameterize or abstract |
AHA principle (Avoid Hasty Abstractions) balance:
- 2 duplications → Wait and see
- 3 duplications → Extract immediately
- Different domain duplications → Don't abstract (e.g., customer validation vs admin validation are different)
## Spec Compliance Verification
Verify that changes comply with the project's documented specifications.
Verification targets:
| Target | What to Check |
|--------|---------------|
| CLAUDE.md / README.md | Conforms to schema definitions, design principles, constraints |
| Type definitions / Zod schemas | New fields reflected in schemas |
| YAML/JSON config files | Follows documented format |
Specific checks:
1. When config files (YAML, etc.) are modified or added:
- Cross-reference with schema definitions in CLAUDE.md, etc.
- No ignored or invalid fields present
- No required fields missing
2. When type definitions or interfaces are modified:
- Documentation schema descriptions are updated
- Existing config files are compatible with new schema
REJECT when these patterns are found:
| Pattern | Problem |
|---------|---------|
| Fields not in the spec | Ignored or unexpected behavior |
| Invalid values per spec | Runtime error or silently ignored |
| Violation of documented constraints | Against design intent |
## Call Chain Verification
When new parameters/fields are added, verify not just the changed file but also callers.
Verification steps:
1. When finding new optional parameters or interface fields, `Grep` all callers
2. Check if all callers pass the new parameter
3. If fallback value (`?? default`) exists, verify if fallback is used as intended
Danger patterns:
| Pattern | Problem | Detection |
|---------|---------|-----------|
| `options.xxx ?? fallback` where all callers omit `xxx` | Feature implemented but always falls back | grep callers |
| Tests set values directly with mocks | Don't go through actual call chain | Check test construction |
| `executeXxx()` doesn't receive `options` it uses internally | No route to pass value from above | Check function signature |
```typescript
// Missing wiring: No route to receive projectCwd
export async function executePiece(config, cwd, task) {
const engine = new PieceEngine(config, cwd, task); // No options
}
// Wired: Can pass projectCwd
export async function executePiece(config, cwd, task, options?) {
const engine = new PieceEngine(config, cwd, task, options);
}
```
Logically dead code due to caller constraints:
Call chain verification applies not only to "missing wiring" but also to the reverse — unnecessary guards for conditions that callers already guarantee.
| Pattern | Problem | Detection |
|---------|---------|-----------|
| TTY check when all callers require TTY | Unreachable branch remains | grep all callers' preconditions |
| Null guard when callers already check null | Redundant defense | Trace caller constraints |
| Runtime type check when TypeScript types constrain | Not trusting type safety | Check TypeScript type constraints |
Verification steps:
1. When finding defensive branches (TTY check, null guard, etc.), grep all callers
2. If all callers already guarantee the condition, guard is unnecessary → REJECT
3. If some callers don't guarantee it, keep the guard
## Quality Attributes
| Attribute | Review Point |
|-----------|--------------|
| Scalability | Design handles increased load |
| Maintainability | Easy to modify and fix |
| Observability | Logging and monitoring enabled |
## Big Picture
Don't get lost in minor "clean code" nitpicks.
Verify:
- How will this code evolve in the future
- Is scaling considered
- Is technical debt being created
- Does it align with business requirements
- Is naming consistent with the domain
## Change Scope Assessment
Check change scope and include in report (non-blocking).
| Scope Size | Lines Changed | Action |
|------------|---------------|--------|
| Small | ~200 lines | Review as-is |
| Medium | 200-500 lines | Review as-is |
| Large | 500+ lines | Continue review. Suggest splitting if possible |
Note: Some tasks require large changes. Don't REJECT based on line count alone.
Verify:
- Changes are logically cohesive (no unrelated changes mixed in)
- Coder's scope declaration matches actual changes
Include as suggestions (non-blocking):
- If splittable, present splitting proposal

417
resources/global/en/knowledge/cqrs-es.md Normal file
View File

@ -0,0 +1,417 @@
# CQRS+ES Knowledge
## Aggregate Design
Aggregates hold only fields necessary for decision-making.
Command Model (Aggregate) role is to "receive commands, make decisions, and emit events". Query data is handled by Read Model (Projection).
"Necessary for decision" means:
- Used in `if`/`require` conditional branches
- Field value referenced when emitting events in instance methods
| Criteria | Judgment |
|----------|----------|
| Aggregate spans multiple transaction boundaries | REJECT |
| Direct references between Aggregates (not ID references) | REJECT |
| Aggregate exceeds 100 lines | Consider splitting |
| Business invariants exist outside Aggregate | REJECT |
| Holding fields not used for decisions | REJECT |
Good Aggregate:
```kotlin
// Only fields necessary for decisions
data class Order(
val orderId: String, // Used when emitting events
val status: OrderStatus // Used for state checking
) {
fun confirm(confirmedBy: String): OrderConfirmedEvent {
require(status == OrderStatus.PENDING) { "Cannot confirm in this state" }
return OrderConfirmedEvent(
orderId = orderId,
confirmedBy = confirmedBy,
confirmedAt = LocalDateTime.now()
)
}
}
// Holding fields not used for decisions (NG)
data class Order(
val orderId: String,
val customerId: String, // Not used for decisions
val shippingAddress: Address, // Not used for decisions
val status: OrderStatus
)
```
Aggregates with no additional operations have ID only:
```kotlin
// When only creation, no additional operations
data class Notification(val notificationId: String) {
companion object {
fun create(customerId: String, message: String): NotificationCreatedEvent {
return NotificationCreatedEvent(
notificationId = UUID.randomUUID().toString(),
customerId = customerId,
message = message
)
}
}
}
```
## Event Design
| Criteria | Judgment |
|----------|----------|
| Event not in past tense (Created → Create) | REJECT |
| Event contains logic | REJECT |
| Event contains internal state of other Aggregates | REJECT |
| Event schema not version controlled | Warning |
| CRUD-style events (Updated, Deleted) | Needs review |
Good Events:
```kotlin
// Good: Domain intent is clear
OrderPlaced, PaymentReceived, ItemShipped
// Bad: CRUD style
OrderUpdated, OrderDeleted
```
Event Granularity:
- Too fine: `OrderFieldChanged` → Domain intent unclear
- Appropriate: `ShippingAddressChanged` → Intent is clear
- Too coarse: `OrderModified` → What changed is unclear
## Command Handlers
| Criteria | Judgment |
|----------|----------|
| Handler directly manipulates DB | REJECT |
| Handler modifies multiple Aggregates | REJECT |
| No command validation | REJECT |
| Handler executes queries to make decisions | Needs review |
Good Command Handler:
```
1. Receive command
2. Restore Aggregate from event store
3. Apply command to Aggregate
4. Save emitted events
```
## Projection Design
| Criteria | Judgment |
|----------|----------|
| Projection issues commands | REJECT |
| Projection references Write model | REJECT |
| Single projection serves multiple use cases | Needs review |
| Design that cannot be rebuilt | REJECT |
Good Projection:
- Optimized for specific read use case
- Idempotently reconstructible from events
- Completely independent from Write model
## Query Side Design
Controller uses QueryGateway. Does not use Repository directly.
Types between layers:
- `application/query/` - Query result types (e.g., `OrderDetail`)
- `adapter/protocol/` - REST response types (e.g., `OrderDetailResponse`)
- QueryHandler returns application layer types, Controller converts to adapter layer types
```kotlin
// application/query/OrderDetail.kt
data class OrderDetail(
val orderId: String,
val customerName: String,
val totalAmount: Money
)
// adapter/protocol/OrderDetailResponse.kt
data class OrderDetailResponse(...) {
companion object {
fun from(detail: OrderDetail) = OrderDetailResponse(...)
}
}
// QueryHandler - returns application layer type
@QueryHandler
fun handle(query: GetOrderDetailQuery): OrderDetail? {
val entity = repository.findById(query.id) ?: return null
return OrderDetail(...)
}
// Controller - converts to adapter layer type
@GetMapping("/{id}")
fun getById(@PathVariable id: String): ResponseEntity<OrderDetailResponse> {
val detail = queryGateway.query(
GetOrderDetailQuery(id),
OrderDetail::class.java
).join() ?: throw NotFoundException("...")
return ResponseEntity.ok(OrderDetailResponse.from(detail))
}
```
Structure:
```
Controller (adapter) → QueryGateway → QueryHandler (application) → Repository
↓ ↓
Response.from(detail) OrderDetail
```
## Eventual Consistency
| Situation | Response |
|-----------|----------|
| UI expects immediate updates | Redesign or polling/WebSocket |
| Consistency delay exceeds tolerance | Reconsider architecture |
| Compensating transactions undefined | Request failure scenario review |
## Saga vs EventHandler
Saga is used only for "operations between multiple aggregates where contention occurs".
Cases where Saga is needed:
```
When multiple actors compete for the same resource
Example: Inventory reservation (10 people ordering the same product simultaneously)
OrderPlacedEvent
↓ InventoryReservationSaga
ReserveInventoryCommand → Inventory aggregate (serializes concurrent execution)
↓
InventoryReservedEvent → ConfirmOrderCommand
InventoryReservationFailedEvent → CancelOrderCommand
```
Cases where Saga is not needed:
```
Non-competing operations
Example: Inventory release on order cancellation
OrderCancelledEvent
↓ InventoryReleaseHandler (simple EventHandler)
ReleaseInventoryCommand
↓
InventoryReleasedEvent
```
Decision criteria:
| Situation | Saga | EventHandler |
|-----------|------|--------------|
| Resource contention exists | Use | - |
| Compensating transaction needed | Use | - |
| Non-competing simple coordination | - | Use |
| Retry on failure is sufficient | - | Use |
Anti-pattern:
```kotlin
// NG - Using Saga for lifecycle management
@Saga
class OrderLifecycleSaga {
// Tracking all order state transitions in Saga
// PLACED → CONFIRMED → SHIPPED → DELIVERED
}
// OK - Saga only for operations requiring eventual consistency
@Saga
class InventoryReservationSaga {
// Only for inventory reservation concurrency control
}
```
Saga is not a lifecycle management tool. Create it per "operation" that requires eventual consistency.
## Exception vs Event (Failure Handling)
Failures not requiring audit use exceptions, failures requiring audit use events.
Exception approach (recommended: most cases):
```kotlin
// Domain model: Throws exception on validation failure
fun reserveInventory(orderId: String, quantity: Int): InventoryReservedEvent {
if (availableQuantity < quantity) {
throw InsufficientInventoryException("Insufficient inventory")
}
return InventoryReservedEvent(productId, orderId, quantity)
}
// Saga: Catch with exceptionally and perform compensating action
commandGateway.send<Any>(command)
.exceptionally { ex ->
commandGateway.send<Any>(CancelOrderCommand(
orderId = orderId,
reason = ex.cause?.message ?: "Inventory reservation failed"
))
null
}
```
Event approach (rare cases):
```kotlin
// Only when audit is required
data class PaymentFailedEvent(
val paymentId: String,
val reason: String,
val attemptedAmount: Money
) : PaymentEvent
```
Decision criteria:
| Question | Exception | Event |
|----------|-----------|-------|
| Need to check this failure later? | No | Yes |
| Required by regulations/compliance? | No | Yes |
| Only Saga cares about the failure? | Yes | No |
| Is there value in keeping it in Event Store? | No | Yes |
Default is exception approach. Consider events only when audit requirements exist.
## Abstraction Level Evaluation
**Conditional branch proliferation detection:**
| Pattern | Judgment |
|---------|----------|
| Same if-else pattern in 3+ places | Abstract with polymorphism → REJECT |
| switch/case with 5+ branches | Consider Strategy/Map pattern |
| Event type branching proliferating | Separate event handlers → REJECT |
| Complex state branching in Aggregate | Consider State Pattern |
**Abstraction level mismatch detection:**
| Pattern | Problem | Fix |
|---------|---------|-----|
| DB operation details in CommandHandler | Responsibility violation | Separate to Repository layer |
| Business logic in EventHandler | Responsibility violation | Extract to domain service |
| Persistence in Aggregate | Layer violation | Change to EventStore route |
| Calculation logic in Projection | Hard to maintain | Extract to dedicated service |
Good abstraction examples:
```kotlin
// Event type branching proliferation (NG)
@EventHandler
fun on(event: DomainEvent) {
when (event) {
is OrderPlacedEvent -> handleOrderPlaced(event)
is OrderConfirmedEvent -> handleOrderConfirmed(event)
is OrderShippedEvent -> handleOrderShipped(event)
// ...keeps growing
}
}
// Separate handlers per event (OK)
@EventHandler
fun on(event: OrderPlacedEvent) { ... }
@EventHandler
fun on(event: OrderConfirmedEvent) { ... }
@EventHandler
fun on(event: OrderShippedEvent) { ... }
```
```kotlin
// Complex state branching (NG)
fun process(command: ProcessCommand) {
when (status) {
PENDING -> if (command.type == "approve") { ... } else if (command.type == "reject") { ... }
APPROVED -> if (command.type == "ship") { ... }
// ...gets complex
}
}
// Abstracted with State Pattern (OK)
sealed class OrderState {
abstract fun handle(command: ProcessCommand): List<DomainEvent>
}
class PendingState : OrderState() {
override fun handle(command: ProcessCommand) = when (command) {
is ApproveCommand -> listOf(OrderApprovedEvent(...))
is RejectCommand -> listOf(OrderRejectedEvent(...))
else -> throw InvalidCommandException()
}
}
```
## Anti-pattern Detection
REJECT if found:
| Anti-pattern | Problem |
|--------------|---------|
| CRUD Disguise | Just splitting CRUD into Command/Query |
| Anemic Domain Model | Aggregate is just a data structure |
| Event Soup | Meaningless events proliferate |
| Temporal Coupling | Implicit dependency on event order |
| Missing Events | Important domain events are missing |
| God Aggregate | All responsibilities in one Aggregate |
## Test Strategy
Separate test strategies by layer.
Test Pyramid:
```
┌─────────────┐
│ E2E Test │ ← Few: Overall flow confirmation
├─────────────┤
│ Integration │ ← Command→Event→Projection→Query coordination
├─────────────┤
│ Unit Test │ ← Many: Each layer tested independently
└─────────────┘
```
Command side (Aggregate):
```kotlin
// Using AggregateTestFixture
@Test
fun `confirm command emits event`() {
fixture
.given(OrderPlacedEvent(...))
.`when`(ConfirmOrderCommand(orderId, confirmedBy))
.expectSuccessfulHandlerExecution()
.expectEvents(OrderConfirmedEvent(...))
}
```
Query side:
```kotlin
// Direct Read Model setup + QueryGateway
@Test
fun `can get order details`() {
// Given: Setup Read Model directly
orderRepository.save(OrderEntity(...))
// When: Execute query via QueryGateway
val detail = queryGateway.query(GetOrderDetailQuery(orderId), ...).join()
// Then
assertEquals(expectedDetail, detail)
}
```
Checklist:
| Aspect | Judgment |
|--------|----------|
| Aggregate tests verify events not state | Required |
| Query side tests don't create data via Command | Recommended |
| Integration tests consider Axon async processing | Required |
## Infrastructure Layer
Check:
- Is event store choice appropriate?
- Does messaging infrastructure meet requirements?
- Is snapshot strategy defined?
- Is event serialization format appropriate?

497
resources/global/en/knowledge/frontend.md Normal file
View File

@ -0,0 +1,497 @@
# Frontend Knowledge
## Component Design
Do not write everything in one file. Always split components.
Required splits:
- Has its own state → Must split
- JSX over 50 lines → Split
- Reusable → Split
- Multiple responsibilities → Split
- Independent section within page → Split
| Criteria | Judgment |
|----------|----------|
| Component over 200 lines | Consider splitting |
| Component over 300 lines | REJECT |
| Display and logic mixed | Consider separation |
| Props drilling (3+ levels) | Consider state management |
| Component with multiple responsibilities | REJECT |
Good Component:
- Single responsibility: Does one thing well
- Self-contained: Dependencies are clear
- Testable: Side effects are isolated
Component Classification:
| Type | Responsibility | Example |
|------|----------------|---------|
| Container | Data fetching, state management | `UserListContainer` |
| Presentational | Display only | `UserCard` |
| Layout | Arrangement, structure | `PageLayout`, `Grid` |
| Utility | Common functionality | `ErrorBoundary`, `Portal` |
Directory Structure:
```
features/{feature-name}/
├── components/
│ ├── {feature}-view.tsx # Main view (composes children)
│ ├── {sub-component}.tsx # Sub-components
│ └── index.ts
├── hooks/
├── types.ts
└── index.ts
```
## State Management
Child components do not modify their own state. They bubble events to parent, and parent manipulates state.
```tsx
// ❌ Child modifies its own state
const ChildBad = ({ initialValue }: { initialValue: string }) => {
const [value, setValue] = useState(initialValue)
return <input value={value} onChange={e => setValue(e.target.value)} />
}
// ✅ Parent manages state, child notifies via callback
const ChildGood = ({ value, onChange }: { value: string; onChange: (v: string) => void }) => {
return <input value={value} onChange={e => onChange(e.target.value)} />
}
const Parent = () => {
const [value, setValue] = useState('')
return <ChildGood value={value} onChange={setValue} />
}
```
Exception (OK for child to have local state):
- UI-only temporary state (hover, focus, animation)
- Completely local state that doesn't need to be communicated to parent
| Criteria | Judgment |
|----------|----------|
| Unnecessary global state | Consider localizing |
| Same state managed in multiple places | Needs normalization |
| State changes from child to parent (reverse data flow) | REJECT |
| API response stored as-is in state | Consider normalization |
| Inappropriate useEffect dependencies | REJECT |
State Placement Guidelines:
| State Nature | Recommended Placement |
|--------------|----------------------|
| Temporary UI state (modal open/close, etc.) | Local (useState) |
| Form input values | Local or form library |
| Shared across multiple components | Context or state management library |
| Server data cache | Data fetching library (TanStack Query, etc.) |
## Data Fetching
API calls are made in root (View) components and passed to children via props.
```tsx
// ✅ CORRECT - Fetch at root, pass to children
const OrderDetailView = () => {
const { data: order, isLoading, error } = useGetOrder(orderId)
const { data: items } = useListOrderItems(orderId)
if (isLoading) return <Skeleton />
if (error) return <ErrorDisplay error={error} />
return (
<OrderSummary
order={order}
items={items}
onItemSelect={handleItemSelect}
/>
)
}
// ❌ WRONG - Child fetches its own data
const OrderSummary = ({ orderId }) => {
const { data: order } = useGetOrder(orderId)
// ...
}
```
When UI state changes affect parameters (week switching, filters, etc.):
Manage state at View level and pass callbacks to components.
```tsx
// ✅ CORRECT - State managed at View level
const ScheduleView = () => {
const [currentWeek, setCurrentWeek] = useState(startOfWeek(new Date()))
const { data } = useListSchedules({
from: format(currentWeek, 'yyyy-MM-dd'),
to: format(endOfWeek(currentWeek), 'yyyy-MM-dd'),
})
return (
<WeeklyCalendar
schedules={data?.items ?? []}
currentWeek={currentWeek}
onWeekChange={setCurrentWeek}
/>
)
}
// ❌ WRONG - Component manages state + data fetching
const WeeklyCalendar = ({ facilityId }) => {
const [currentWeek, setCurrentWeek] = useState(...)
const { data } = useListSchedules({ facilityId, from, to })
// ...
}
```
Exceptions (component-level fetching allowed):
| Case | Reason |
|------|--------|
| Infinite scroll | Depends on scroll position (internal UI state) |
| Search autocomplete | Real-time search based on input value |
| Independent widget | Notification badge, weather, etc. Completely unrelated to parent data |
| Real-time updates | WebSocket/Polling auto-updates |
| Modal detail fetch | Fetch additional data only when opened |
Decision criteria: "Is there no point in parent managing this / Does it not affect parent?"
| Criteria | Judgment |
|----------|----------|
| Direct fetch in component | Separate to Container layer |
| No error handling | REJECT |
| Loading state not handled | REJECT |
| No cancellation handling | Warning |
| N+1 query-like fetching | REJECT |
## Shared Components and Abstraction
Common UI patterns should be shared components. Copy-paste of inline styles is prohibited.
```tsx
// ❌ WRONG - Copy-pasted inline styles
<button className="p-2 text-[var(--text-secondary)] hover:...">
<X className="w-5 h-5" />
</button>
// ✅ CORRECT - Use shared component
<IconButton onClick={onClose} aria-label="Close">
<X className="w-5 h-5" />
</IconButton>
```
Patterns to make shared components:
- Icon buttons (close, edit, delete, etc.)
- Loading/error displays
- Status badges
- Tab switching
- Label + value display (detail screens)
- Search input
- Color legends
Avoid over-generalization:
```tsx
// ❌ WRONG - Forcing stepper variant into IconButton
export const iconButtonVariants = cva('...', {
variants: {
variant: {
default: '...',
outlined: '...', // ← Stepper-specific, not used elsewhere
},
size: {
medium: 'p-2',
stepper: 'w-8 h-8', // ← Only used with outlined
},
},
})
// ✅ CORRECT - Purpose-specific component
export function StepperButton(props) {
return (
<button className="w-8 h-8 rounded-full border ..." {...props}>
<Plus className="w-4 h-4" />
</button>
)
}
```
Signs to make separate components:
- Implicit constraints like "this variant is always with this size"
- Added variant is clearly different from original component's purpose
- Props specification becomes complex on the usage side
## Abstraction Level Evaluation
**Conditional branch bloat detection:**
| Pattern | Judgment |
|---------|----------|
| Same conditional in 3+ places | Extract to shared component → **REJECT** |
| Props-based branching with 5+ types | Consider component split |
| Nested ternaries in render | Early return or component separation → **REJECT** |
| Type-based render branching | Consider polymorphic components |
**Abstraction level mismatch detection:**
| Pattern | Problem | Fix |
|---------|---------|-----|
| Data fetching logic mixed in JSX | Hard to read | Extract to custom hook |
| Business logic mixed in component | Responsibility violation | Separate to hooks/utils |
| Style calculation logic scattered | Hard to maintain | Extract to utility function |
| Same transformation in multiple places | DRY violation | Extract to common function |
Good abstraction examples:
```tsx
// ❌ Conditional bloat
function UserBadge({ user }) {
if (user.role === 'admin') {
return <span className="bg-red-500">Admin</span>
} else if (user.role === 'moderator') {
return <span className="bg-yellow-500">Moderator</span>
} else if (user.role === 'premium') {
return <span className="bg-purple-500">Premium</span>
} else {
return <span className="bg-gray-500">User</span>
}
}
// ✅ Abstracted with Map
const ROLE_CONFIG = {
admin: { label: 'Admin', className: 'bg-red-500' },
moderator: { label: 'Moderator', className: 'bg-yellow-500' },
premium: { label: 'Premium', className: 'bg-purple-500' },
default: { label: 'User', className: 'bg-gray-500' },
}
function UserBadge({ user }) {
const config = ROLE_CONFIG[user.role] ?? ROLE_CONFIG.default
return <span className={config.className}>{config.label}</span>
}
```
```tsx
// ❌ Mixed abstraction levels
function OrderList() {
const [orders, setOrders] = useState([])
useEffect(() => {
fetch('/api/orders')
.then(res => res.json())
.then(data => setOrders(data))
}, [])
return orders.map(order => (
<div>{order.total.toLocaleString()} USD</div>
))
}
// ✅ Aligned abstraction levels
function OrderList() {
const { data: orders } = useOrders() // Hide data fetching
return orders.map(order => (
<OrderItem key={order.id} order={order} />
))
}
```
## Frontend and Backend Separation of Concerns
### Display Format Responsibility
Backend returns "data", frontend converts to "display format".
```tsx
// ✅ Frontend: Convert to display format
export function formatPrice(amount: number): string {
return `$${amount.toLocaleString()}`
}
export function formatDate(date: Date): string {
return format(date, 'MMM d, yyyy')
}
```
| Criteria | Judgment |
|----------|----------|
| Backend returns display strings | Suggest design review |
| Same format logic copy-pasted | Unify to utility function |
| Inline formatting in component | Extract to function |
### Domain Logic Placement (Smart UI Elimination)
Domain logic (business rules) belongs in the backend. Frontend only displays and edits state.
What is domain logic:
- Aggregate business rules (stock validation, price calculation, status transitions)
- Business constraint validation
- Invariant enforcement
Frontend responsibilities:
- Display state received from server
- Collect user input and send commands to backend
- Manage UI-only temporary state (focus, hover, modal open/close)
- Display format conversion (formatting, sorting, filtering)
| Criteria | Judgment |
|----------|----------|
| Price calculation/stock validation in frontend | Move to backend → **REJECT** |
| Status transition rules in frontend | Move to backend → **REJECT** |
| Business validation in frontend | Move to backend → **REJECT** |
| Recalculating server-computable values in frontend | Redundant → **REJECT** |
Good vs Bad Examples:
```tsx
// ❌ BAD - Business rules in frontend
function OrderForm({ order }: { order: Order }) {
const totalPrice = order.items.reduce((sum, item) =>
sum + item.price * item.quantity, 0
)
const canCheckout = totalPrice >= 100 && order.items.every(i => i.stock > 0)
return <button disabled={!canCheckout}>Checkout</button>
}
// ✅ GOOD - Display state received from server
function OrderForm({ order }: { order: Order }) {
// totalPrice, canCheckout are received from server
return (
<>
<div>{formatPrice(order.totalPrice)}</div>
<button disabled={!order.canCheckout}>Checkout</button>
</>
)
}
```
```tsx
// ❌ BAD - Status transition logic in frontend
function TaskCard({ task }: { task: Task }) {
const canStart = task.status === 'pending' && task.assignee !== null
const canComplete = task.status === 'in_progress' && /* complex conditions... */
return (
<>
<button onClick={startTask} disabled={!canStart}>Start</button>
<button onClick={completeTask} disabled={!canComplete}>Complete</button>
</>
)
}
// ✅ GOOD - Server returns allowed actions
function TaskCard({ task }: { task: Task }) {
// task.allowedActions = ['start', 'cancel'], etc., calculated by server
const canStart = task.allowedActions.includes('start')
const canComplete = task.allowedActions.includes('complete')
return (
<>
<button onClick={startTask} disabled={!canStart}>Start</button>
<button onClick={completeTask} disabled={!canComplete}>Complete</button>
</>
)
}
```
Exceptions (OK to have logic in frontend):
| Case | Reason |
|------|--------|
| UI-only validation | UX feedback like "required field", "max length" (must also validate on server) |
| Client-side filter/sort | Changing display order of lists received from server |
| Display condition branching | UI control like "show details if logged in" |
| Real-time feedback | Preview display during input |
Decision criteria: "Would the business break if this calculation differs from the server?"
- YES → Place in backend (domain logic)
- NO → OK in frontend (display logic)
## Performance
| Criteria | Judgment |
|----------|----------|
| Unnecessary re-renders | Needs optimization |
| Large lists without virtualization | Warning |
| Unoptimized images | Warning |
| Unused code in bundle | Check tree-shaking |
| Excessive memoization | Verify necessity |
Optimization Checklist:
- Are `React.memo` / `useMemo` / `useCallback` appropriate?
- Are large lists using virtual scroll?
- Is Code Splitting appropriate?
- Are images lazy loaded?
Anti-patterns:
```tsx
// ❌ New object every render
<Child style={{ color: 'red' }} />
// ✅ Constant or useMemo
const style = useMemo(() => ({ color: 'red' }), []);
<Child style={style} />
```
## Accessibility
| Criteria | Judgment |
|----------|----------|
| Interactive elements without keyboard support | REJECT |
| Images without alt attribute | REJECT |
| Form elements without labels | REJECT |
| Information conveyed by color only | REJECT |
| Missing focus management (modals, etc.) | REJECT |
Checklist:
- Using semantic HTML?
- Are ARIA attributes appropriate (not excessive)?
- Is keyboard navigation possible?
- Does it make sense with a screen reader?
- Is color contrast sufficient?
## TypeScript/Type Safety
| Criteria | Judgment |
|----------|----------|
| Use of `any` type | REJECT |
| Excessive type assertions (as) | Needs review |
| No Props type definition | REJECT |
| Inappropriate event handler types | Needs fix |
## Frontend Security
| Criteria | Judgment |
|----------|----------|
| dangerouslySetInnerHTML usage | Check XSS risk |
| Unsanitized user input | REJECT |
| Sensitive data stored in frontend | REJECT |
| CSRF token not used | Needs verification |
## Testability
| Criteria | Judgment |
|----------|----------|
| No data-testid, etc. | Warning |
| Structure difficult to test | Consider separation |
| Business logic embedded in UI | REJECT |
## Anti-pattern Detection
REJECT if found:
| Anti-pattern | Problem |
|--------------|---------|
| God Component | All features concentrated in one component |
| Prop Drilling | Deep props bucket brigade |
| Inline Styles abuse | Maintainability degradation |
| useEffect hell | Dependencies too complex |
| Premature Optimization | Unnecessary memoization |
| Magic Strings | Hardcoded strings |
| Hidden Dependencies | Child components with hidden API calls |
| Over-generalization | Components forced to be generic |

164
resources/global/en/knowledge/security.md Normal file
View File

@ -0,0 +1,164 @@
# Security Knowledge
## AI-Generated Code Security Issues
AI-generated code has unique vulnerability patterns.
| Pattern | Risk | Example |
|---------|------|---------|
| Plausible but dangerous defaults | High | `cors: { origin: '*' }` looks fine but is dangerous |
| Outdated security practices | Medium | Using deprecated encryption, old auth patterns |
| Incomplete validation | High | Validates format but not business rules |
| Over-trusting inputs | Critical | Assumes internal APIs are always safe |
| Copy-paste vulnerabilities | High | Same dangerous pattern repeated in multiple files |
Require extra scrutiny:
- Auth/authorization logic (AI tends to miss edge cases)
- Input validation (AI may check syntax but miss semantics)
- Error messages (AI may expose internal details)
- Config files (AI may use dangerous defaults from training data)
## Injection Attacks
**SQL Injection:**
- SQL construction via string concatenation → REJECT
- Not using parameterized queries → REJECT
- Unsanitized input in ORM raw queries → REJECT
```typescript
// NG
db.query(`SELECT * FROM users WHERE id = ${userId}`)
// OK
db.query('SELECT * FROM users WHERE id = ?', [userId])
```
**Command Injection:**
- Unvalidated input in `exec()`, `spawn()` → REJECT
- Insufficient escaping in shell command construction → REJECT
```typescript
// NG
exec(`ls ${userInput}`)
// OK
execFile('ls', [sanitizedInput])
```
**XSS (Cross-Site Scripting):**
- Unescaped output to HTML/JS → REJECT
- Improper use of `innerHTML`, `dangerouslySetInnerHTML` → REJECT
- Direct embedding of URL parameters → REJECT
## Authentication & Authorization
**Authentication issues:**
- Hardcoded credentials → Immediate REJECT
- Plaintext password storage → Immediate REJECT
- Weak hash algorithms (MD5, SHA1) → REJECT
- Improper session token management → REJECT
**Authorization issues:**
- Missing permission checks → REJECT
- IDOR (Insecure Direct Object Reference) → REJECT
- Privilege escalation possibility → REJECT
```typescript
// NG - No permission check
app.get('/user/:id', (req, res) => {
return db.getUser(req.params.id)
})
// OK
app.get('/user/:id', authorize('read:user'), (req, res) => {
if (req.user.id !== req.params.id && !req.user.isAdmin) {
return res.status(403).send('Forbidden')
}
return db.getUser(req.params.id)
})
```
## Data Protection
**Sensitive information exposure:**
- Hardcoded API keys, secrets → Immediate REJECT
- Sensitive info in logs → REJECT
- Internal info exposure in error messages → REJECT
- Committed `.env` files → REJECT
**Data validation:**
- Unvalidated input values → REJECT
- Missing type checks → REJECT
- No size limits set → REJECT
## Cryptography
- Use of weak crypto algorithms → REJECT
- Fixed IV/Nonce usage → REJECT
- Hardcoded encryption keys → Immediate REJECT
- No HTTPS (production) → REJECT
## File Operations
**Path Traversal:**
- File paths containing user input → REJECT
- Insufficient `../` sanitization → REJECT
```typescript
// NG
const filePath = path.join(baseDir, userInput)
fs.readFile(filePath)
// OK
const safePath = path.resolve(baseDir, userInput)
if (!safePath.startsWith(path.resolve(baseDir))) {
throw new Error('Invalid path')
}
```
**File Upload:**
- No file type validation → REJECT
- No file size limits → REJECT
- Allowing executable file uploads → REJECT
## Dependencies
- Packages with known vulnerabilities → REJECT
- Unmaintained packages → Warning
- Unnecessary dependencies → Warning
## Error Handling
- Stack trace exposure in production → REJECT
- Detailed error message exposure → REJECT
- Swallowing security events → REJECT
## Rate Limiting & DoS Protection
- No rate limiting (auth endpoints) → Warning
- Resource exhaustion attack possibility → Warning
- Infinite loop possibility → REJECT
## OWASP Top 10 Checklist
| Category | Check Items |
|----------|-------------|
| A01 Broken Access Control | Authorization checks, CORS config |
| A02 Cryptographic Failures | Encryption, sensitive data protection |
| A03 Injection | SQL, Command, XSS |
| A04 Insecure Design | Security design patterns |
| A05 Security Misconfiguration | Default settings, unnecessary features |
| A06 Vulnerable Components | Dependency vulnerabilities |
| A07 Auth Failures | Authentication mechanisms |
| A08 Software Integrity | Code signing, CI/CD |
| A09 Logging Failures | Security logging |
| A10 SSRF | Server-side requests |

428
resources/global/en/personas/architecture-reviewer.md
View File

@ -40,434 +40,6 @@ Code is read far more often than it is written. Poorly structured code destroys
- Give vague feedback ("clean this up" is prohibited) - Give vague feedback ("clean this up" is prohibited)
- Review AI-specific issues (AI Reviewer's job) - Review AI-specific issues (AI Reviewer's job)
## Review Target Distinction
**Important**: Distinguish between source files and generated files.
| Type | Location | Review Target |
|------|----------|---------------|
| Generated reports | `.takt/reports/` | Not a review target |
| Reports in git diff | `.takt/reports/` | **Ignore** |
**About template files:**
- YAML and Markdown files in `resources/` are templates
- `{report_dir}`, `{task}` are placeholders (replaced at runtime)
- Even if expanded values appear in git diff for report files, they are NOT hardcoded
**To avoid false positives:**
1. Before flagging "hardcoded values", **verify if the file is source or report**
2. Files under `.takt/reports/` are generated during piece execution - not review targets
3. Ignore generated files even if they appear in git diff
## Review Perspectives
### 1. Structure & Design
**File Organization:**
| Criteria | Judgment |
|----------|----------|
| Single file > 200 lines | Consider splitting |
| Single file > 300 lines | REJECT |
| Single file with multiple responsibilities | REJECT |
| Unrelated code coexisting | REJECT |
**Module Structure:**
- High cohesion: Related functionality grouped together
- Low coupling: Minimal inter-module dependencies
- No circular dependencies
- Appropriate directory hierarchy
**Function Design:**
- One responsibility per function
- Consider splitting functions over 30 lines
- Side effects clearly defined
**Layer Design:**
- Dependency direction: Upper layers -> Lower layers (reverse prohibited)
- Controller -> Service -> Repository flow maintained
- 1 interface = 1 responsibility (no giant Service classes)
**Directory Structure:**
Structure pattern selection:
| Pattern | Use Case | Example |
|---------|----------|---------|
| Layered | Small scale, CRUD-centric | `controllers/`, `services/`, `repositories/` |
| Vertical Slice | Medium-large scale, high feature independence | `features/auth/`, `features/order/` |
| Hybrid | Common foundation + feature modules | `core/` + `features/` |
Vertical Slice Architecture (organizing code by feature):
```
src/
├── features/
│ ├── auth/
│ │ ├── LoginCommand.ts
│ │ ├── LoginHandler.ts
│ │ ├── AuthRepository.ts
│ │ └── auth.test.ts
│ └── order/
│ ├── CreateOrderCommand.ts
│ ├── CreateOrderHandler.ts
│ └── ...
└── shared/ # Shared across features
├── database/
└── middleware/
```
Vertical Slice criteria:
| Criteria | Judgment |
|----------|----------|
| Single feature spans 3+ layers | Consider slicing |
| Minimal inter-feature dependencies | Recommend slicing |
| Over 50% shared processing | Keep layered |
| Team organized by features | Slicing required |
Prohibited patterns:
| Pattern | Problem |
|---------|---------|
| Bloated `utils/` | Becomes graveyard of unclear responsibilities |
| Lazy placement in `common/` | Dependencies become unclear |
| Excessive nesting (4+ levels) | Navigation difficulty |
| Mixed features and layers | `features/services/` prohibited |
**Separation of Concerns:**
- Read and write responsibilities separated
- Data fetching at root (View/Controller), passed to children
- Error handling centralized (no try-catch scattered everywhere)
- Business logic not leaking into Controller/View
### 2. Code Quality
**Mandatory checks:**
- Use of `any` type -> **Immediate REJECT**
- Overuse of fallback values (`?? 'unknown'`) -> **REJECT** (see examples below)
- Explanatory comments (What/How comments) -> **REJECT** (see examples below)
- Unused code ("just in case" code) -> **REJECT** (see examples below)
- Direct state mutation (not immutable) -> **REJECT** (see examples below)
**Design principles:**
- Simple > Easy: Readability prioritized
- DRY: No more than 3 duplications
- YAGNI: Only what's needed now
- Fail Fast: Errors detected and reported early
- Idiomatic: Follows language/framework conventions
**Explanatory Comment (What/How) Detection Criteria:**
Comments must only explain design decisions not evident from code (Why), never restate what the code does (What/How). If the code is clear enough, no comment is needed at all.
| Judgment | Criteria |
|----------|----------|
| **REJECT** | Restates code behavior in natural language |
| **REJECT** | Repeats what is already obvious from function/variable names |
| **REJECT** | JSDoc that only paraphrases the function name without adding information |
| OK | Explains why a particular implementation was chosen |
| OK | Explains the reason behind seemingly unusual behavior |
| Best | No comment needed — the code itself communicates intent |
```typescript
// ❌ REJECT - Restates code (What)
// If interrupted, abort immediately
if (status === 'interrupted') {
return ABORT_STEP;
}
// ❌ REJECT - Restates the loop
// Check transitions in order
for (const transition of step.transitions) {
// ❌ REJECT - Repeats the function name
/** Check if status matches transition condition. */
export function matchesCondition(status: Status, condition: TransitionCondition): boolean {
// ✅ OK - Design decision (Why)
// User interruption takes priority over piece-defined transitions
if (status === 'interrupted') {
return ABORT_STEP;
}
// ✅ OK - Reason behind seemingly odd behavior
// stay can cause loops, but is only used when explicitly specified by the user
return step.name;
// ✅ Best - No comment needed. Code is self-evident
if (status === 'interrupted') {
return ABORT_STEP;
}
```
**Direct State Mutation Detection Criteria:**
Directly mutating objects or arrays makes changes hard to track and causes unexpected side effects. Always use spread operators or immutable operations to return new objects.
```typescript
// ❌ REJECT - Direct array mutation
const steps: Step[] = getSteps();
steps.push(newStep); // Mutates original array
steps.splice(index, 1); // Mutates original array
steps[0].status = 'done'; // Nested object also mutated directly
// ✅ OK - Immutable operations
const withNew = [...steps, newStep];
const without = steps.filter((_, i) => i !== index);
const updated = steps.map((s, i) =>
i === 0 ? { ...s, status: 'done' } : s
);
// ❌ REJECT - Direct object mutation
function updateConfig(config: Config) {
config.logLevel = 'debug'; // Mutates argument directly
config.steps.push(newStep); // Nested mutation too
return config;
}
// ✅ OK - Returns new object
function updateConfig(config: Config): Config {
return {
...config,
logLevel: 'debug',
steps: [...config.steps, newStep],
};
}
```
### 3. Security
- Injection prevention (SQL, Command, XSS)
- User input validation
- Hardcoded sensitive information
### 4. Testability
- Dependency injection enabled
- Mockable design
- Tests are written
### 5. Anti-Pattern Detection
**REJECT** when these patterns are found:
| Anti-Pattern | Problem |
|--------------|---------|
| God Class/Component | Single class with too many responsibilities |
| Feature Envy | Frequently accessing other modules' data |
| Shotgun Surgery | Single change ripples across multiple files |
| Over-generalization | Variants and extension points not currently needed |
| Hidden Dependencies | Child components implicitly calling APIs etc. |
| Non-idiomatic | Custom implementation ignoring language/FW conventions |
| Logically dead defensive code | Guards for conditions already guaranteed by all callers |
**Logically dead defensive code:**
Call chain verification applies not only to "missing wiring" but also to the reverse — **unnecessary guards for conditions that callers already guarantee**.
| Pattern | Problem | Detection |
|---------|---------|-----------|
| TTY check when all callers require TTY | Unreachable branch remains | grep all callers' preconditions |
| Null guard when callers already check null | Redundant defense | Trace caller constraints |
| Runtime type check when TypeScript types constrain | Not trusting type safety | Check TypeScript type constraints |
**Verification:**
1. When you find a defensive branch (TTY check, null guard, etc.), grep all callers
2. If all callers already guarantee the condition, the guard is unnecessary → **REJECT**
3. If some callers don't guarantee it, keep the guard
### 6. Abstraction Level Evaluation
**Conditional Branch Proliferation Detection:**
| Pattern | Judgment |
|---------|----------|
| Same if-else pattern in 3+ places | Abstract with polymorphism → **REJECT** |
| switch/case with 5+ branches | Consider Strategy/Map pattern |
| Flag arguments changing behavior | Split into separate functions → **REJECT** |
| Type-based branching (instanceof/typeof) | Replace with polymorphism → **REJECT** |
| Nested conditionals (3+ levels) | Early return or extract → **REJECT** |
**Abstraction Level Mismatch Detection:**
| Pattern | Problem | Fix |
|---------|---------|-----|
| Low-level details in high-level processing | Hard to read | Extract details to functions |
| Mixed abstraction levels in one function | Cognitive load | Align to same granularity |
| DB operations mixed with business logic | Responsibility violation | Separate to Repository layer |
| Config values mixed with processing logic | Hard to change | Externalize configuration |
**Good Abstraction Examples:**
```typescript
// ❌ Proliferating conditionals
function process(type: string) {
if (type === 'A') { /* process A */ }
else if (type === 'B') { /* process B */ }
else if (type === 'C') { /* process C */ }
// ...continues
}
// ✅ Abstract with Map pattern
const processors: Record<string, () => void> = {
A: processA,
B: processB,
C: processC,
};
function process(type: string) {
processors[type]?.();
}
```
```typescript
// ❌ Mixed abstraction levels
function createUser(data: UserData) {
// High level: business logic
validateUser(data);
// Low level: DB operation details
const conn = await pool.getConnection();
await conn.query('INSERT INTO users...');
conn.release();
}
// ✅ Aligned abstraction levels
function createUser(data: UserData) {
validateUser(data);
await userRepository.save(data); // Details hidden
}
```
### 7. Workaround Detection
**Don't overlook compromises made to "just make it work."**
| Pattern | Example |
|---------|---------|
| Unnecessary package additions | Mystery libraries added just to make things work |
| Test deletion/skipping | `@Disabled`, `.skip()`, commented out |
| Empty implementations/stubs | `return null`, `// TODO: implement`, `pass` |
| Mock data in production | Hardcoded dummy data |
| Swallowed errors | Empty `catch {}`, `rescue nil` |
| Magic numbers | Unexplained `if (status == 3)` |
**Always point these out.** Temporary fixes become permanent.
### 8. Spec Compliance Verification
**Verify that changes comply with the project's documented specifications.**
**Verification targets:**
| Target | What to Check |
|--------|---------------|
| CLAUDE.md / README.md | Conforms to schema definitions, design principles, constraints |
| Type definitions / Zod schemas | New fields reflected in schemas |
| YAML/JSON config files | Follows documented format |
**Specific checks:**
1. When config files (YAML, etc.) are modified or added:
- Cross-reference with schema definitions in CLAUDE.md, etc.
- No ignored or invalid fields present
- No required fields missing
2. When type definitions or interfaces are modified:
- Documentation schema descriptions are updated
- Existing config files are compatible with new schema
3. When piece definitions are modified:
- Correct fields used for step type (normal vs. parallel)
- No unnecessary fields remaining (e.g., `next` on parallel sub-steps)
**REJECT when these patterns are found:**
| Pattern | Problem |
|---------|---------|
| Fields not in the spec | Ignored or unexpected behavior |
| Invalid values per spec | Runtime error or silently ignored |
| Violation of documented constraints | Against design intent |
| Step type / field mismatch | Sign of copy-paste error |
### 9. Quality Attributes
| Attribute | Review Point |
|-----------|--------------|
| Scalability | Design handles increased load |
| Maintainability | Easy to modify and fix |
| Observability | Logging and monitoring enabled |
### 10. Big Picture
**Caution**: Don't get lost in minor "clean code" nitpicks.
Verify:
- How will this code evolve in the future
- Is scaling considered
- Is technical debt being created
- Does it align with business requirements
- Is naming consistent with the domain
### 11. Boy Scout Rule
**Leave the code better than you found it.** If changed files have structural issues, flag them for refactoring within the task scope.
**In scope:**
- Existing issues within changed files (dead code, poor naming, broken abstractions)
- Structural issues within changed modules (mixed responsibilities, unnecessary dependencies)
**Out of scope:**
- Issues in unchanged files (record as existing issues only)
- Refactoring that significantly exceeds the task scope (suggest as non-blocking)
**Judgment:**
| Situation | Judgment |
|-----------|----------|
| Clear issues within changed files | **REJECT** — require fix together |
| Structural issues within changed modules | **REJECT** — fix if within scope |
| Issues in unchanged files | Record only (non-blocking) |
**Following poor existing code as justification for leaving problems is not acceptable.** If existing code is bad, improve it rather than match it.
### 12. Change Scope Assessment
**Check change scope and include in report (non-blocking).**
| Scope Size | Lines Changed | Action |
|------------|---------------|--------|
| Small | ~200 lines | Review as-is |
| Medium | 200-500 lines | Review as-is |
| Large | 500+ lines | Continue review. Suggest splitting if possible |
**Note:** Some tasks require large changes. Don't REJECT based on line count alone.
**Verify:**
- Changes are logically cohesive (no unrelated changes mixed in)
- Coder's scope declaration matches actual changes
**Include as suggestions (non-blocking):**
- If splittable, present splitting proposal
### 13. Circular Review Detection
When review count is provided (e.g., "Review count: 3rd"), adjust judgment accordingly.
**From the 3rd review onwards:**
1. Check if the same type of issues are recurring
2. If recurring, suggest **alternative approaches** rather than detailed fixes
3. Even when REJECTing, include perspective that "a different approach should be considered"
Example: When issues repeat on the 3rd review
- Point out the normal issues
- Note that the same type of issues are recurring
- Explain the limitations of the current approach
- Present alternatives (e.g., redesign with a different pattern, introduce new technology)
**Point**: Rather than repeating "fix this again", step back and suggest a different path.
## Important ## Important
**Be specific.** These are prohibited: **Be specific.** These are prohibited:

111
resources/global/en/personas/cqrs-es-reviewer.md
View File

@ -28,117 +28,6 @@ The truth of a domain is inscribed in events. State is merely a temporary projec
- Snapshot strategies - Snapshot strategies
- Replay and rebuild - Replay and rebuild
## Review Criteria
### 1. Aggregate Design
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Aggregate spans multiple transaction boundaries | REJECT |
| Direct references between Aggregates (not ID references) | REJECT |
| Aggregate exceeds 100 lines | Consider splitting |
| Business invariants exist outside Aggregate | REJECT |
**Good Aggregate:**
- Clear consistency boundary
- References other Aggregates by ID
- Receives commands, emits events
- Protects invariants internally
### 2. Event Design
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Event not in past tense (Created → Create) | REJECT |
| Event contains logic | REJECT |
| Event contains internal state of other Aggregates | REJECT |
| Event schema not version controlled | Warning |
| CRUD-style events (Updated, Deleted) | Needs review |
**Good Events:**
```
// Good: Domain intent is clear
OrderPlaced, PaymentReceived, ItemShipped
// Bad: CRUD style
OrderUpdated, OrderDeleted
```
**Event Granularity:**
- Too fine: `OrderFieldChanged` → Domain intent unclear
- Appropriate: `ShippingAddressChanged` → Intent is clear
- Too coarse: `OrderModified` → What changed is unclear
### 3. Command Handlers
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Handler directly manipulates DB | REJECT |
| Handler modifies multiple Aggregates | REJECT |
| No command validation | REJECT |
| Handler executes queries to make decisions | Needs review |
**Good Command Handler:**
```
1. Receive command
2. Restore Aggregate from event store
3. Apply command to Aggregate
4. Save emitted events
```
### 4. Projection Design
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Projection issues commands | REJECT |
| Projection references Write model | REJECT |
| Single projection serves multiple use cases | Needs review |
| Design that cannot be rebuilt | REJECT |
**Good Projection:**
- Optimized for specific read use case
- Idempotently reconstructible from events
- Completely independent from Write model
### 5. Eventual Consistency
**Required Checks:**
| Situation | Response |
|-----------|----------|
| UI expects immediate updates | Redesign or polling/WebSocket |
| Consistency delay exceeds tolerance | Reconsider architecture |
| Compensating transactions undefined | Request failure scenario review |
### 6. Anti-pattern Detection
**REJECT** if found:
| Anti-pattern | Problem |
|--------------|---------|
| CRUD Disguise | Just splitting CRUD into Command/Query |
| Anemic Domain Model | Aggregate is just a data structure |
| Event Soup | Meaningless events proliferate |
| Temporal Coupling | Implicit dependency on event order |
| Missing Events | Important domain events are missing |
| God Aggregate | All responsibilities in one Aggregate |
### 7. Infrastructure Layer
**Check:**
- Is the event store choice appropriate?
- Does the messaging infrastructure meet requirements?
- Is snapshot strategy defined?
- Is event serialization format appropriate?
## Important ## Important
- **Don't overlook superficial CQRS**: Just splitting CRUD into Command/Query is meaningless - **Don't overlook superficial CQRS**: Just splitting CRUD into Command/Query is meaningless

527
resources/global/en/personas/frontend-reviewer.md
View File

@ -32,533 +32,6 @@ The user interface is the only point of contact between the system and users. No
- WAI-ARIA compliance - WAI-ARIA compliance
- Responsive design - Responsive design
## Review Criteria
### 1. Component Design
**Principle: Do not write everything in one file. Always split components.**
**Required splits:**
- Has its own state → Must split
- JSX over 50 lines → Split
- Reusable → Split
- Multiple responsibilities → Split
- Independent section within page → Split
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Component over 200 lines | Consider splitting |
| Component over 300 lines | REJECT |
| Display and logic mixed | Consider separation |
| Props drilling (3+ levels) | Consider state management |
| Component with multiple responsibilities | REJECT |
**Good Component:**
- Single responsibility: Does one thing well
- Self-contained: Dependencies are clear
- Testable: Side effects are isolated
**Component Classification:**
| Type | Responsibility | Example |
|------|----------------|---------|
| Container | Data fetching, state management | `UserListContainer` |
| Presentational | Display only | `UserCard` |
| Layout | Arrangement, structure | `PageLayout`, `Grid` |
| Utility | Common functionality | `ErrorBoundary`, `Portal` |
**Directory Structure:**
```
features/{feature-name}/
├── components/
│ ├── {feature}-view.tsx # Main view (composes children)
│ ├── {sub-component}.tsx # Sub-components
│ └── index.ts
├── hooks/
├── types.ts
└── index.ts
```
### 2. State Management
**Principle: Child components do not modify their own state. They bubble events to parent, and parent manipulates state.**
```tsx
// ❌ Child modifies its own state
const ChildBad = ({ initialValue }: { initialValue: string }) => {
const [value, setValue] = useState(initialValue)
return <input value={value} onChange={e => setValue(e.target.value)} />
}
// ✅ Parent manages state, child notifies via callback
const ChildGood = ({ value, onChange }: { value: string; onChange: (v: string) => void }) => {
return <input value={value} onChange={e => onChange(e.target.value)} />
}
const Parent = () => {
const [value, setValue] = useState('')
return <ChildGood value={value} onChange={setValue} />
}
```
**Exception (OK for child to have local state):**
- UI-only temporary state (hover, focus, animation)
- Completely local state that doesn't need to be communicated to parent
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Unnecessary global state | Consider localizing |
| Same state managed in multiple places | Needs normalization |
| State changes from child to parent (reverse data flow) | REJECT |
| API response stored as-is in state | Consider normalization |
| Inappropriate useEffect dependencies | REJECT |
**State Placement Guidelines:**
| State Nature | Recommended Placement |
|--------------|----------------------|
| Temporary UI state (modal open/close, etc.) | Local (useState) |
| Form input values | Local or form library |
| Shared across multiple components | Context or state management library |
| Server data cache | Data fetching library (TanStack Query, etc.) |
### 3. Data Fetching
**Principle: API calls are made in root (View) components and passed to children via props.**
```tsx
// ✅ CORRECT - Fetch at root, pass to children
const OrderDetailView = () => {
const { data: order, isLoading, error } = useGetOrder(orderId)
const { data: items } = useListOrderItems(orderId)
if (isLoading) return <Skeleton />
if (error) return <ErrorDisplay error={error} />
return (
<OrderSummary
order={order}
items={items}
onItemSelect={handleItemSelect}
/>
)
}
// ❌ WRONG - Child fetches its own data
const OrderSummary = ({ orderId }) => {
const { data: order } = useGetOrder(orderId)
// ...
}
```
**Reasons:**
- Data flow is explicit and traceable
- Child components are pure presentation (easier to test)
- No hidden dependencies in child components
**When UI state changes affect parameters (week switching, filters, etc.):**
Manage state at View level and pass callbacks to components.
```tsx
// ✅ CORRECT - State managed at View level
const ScheduleView = () => {
const [currentWeek, setCurrentWeek] = useState(startOfWeek(new Date()))
const { data } = useListSchedules({
from: format(currentWeek, 'yyyy-MM-dd'),
to: format(endOfWeek(currentWeek), 'yyyy-MM-dd'),
})
return (
<WeeklyCalendar
schedules={data?.items ?? []}
currentWeek={currentWeek}
onWeekChange={setCurrentWeek}
/>
)
}
// ❌ WRONG - Component manages state + data fetching
const WeeklyCalendar = ({ facilityId }) => {
const [currentWeek, setCurrentWeek] = useState(...)
const { data } = useListSchedules({ facilityId, from, to })
// ...
}
```
**Exceptions (component-level fetching allowed):**
| Case | Reason |
|------|--------|
| Infinite scroll | Depends on scroll position (internal UI state) |
| Search autocomplete | Real-time search based on input value |
| Independent widget | Notification badge, weather, etc. Completely unrelated to parent data |
| Real-time updates | WebSocket/Polling auto-updates |
| Modal detail fetch | Fetch additional data only when opened |
**Decision criteria: "Is there no point in parent managing this / Does it not affect parent?"**
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Direct fetch in component | Separate to Container layer |
| No error handling | REJECT |
| Loading state not handled | REJECT |
| No cancellation handling | Warning |
| N+1 query-like fetching | REJECT |
### 4. Shared Components and Abstraction
**Principle: Common UI patterns should be shared components. Copy-paste of inline styles is prohibited.**
```tsx
// ❌ WRONG - Copy-pasted inline styles
<button className="p-2 text-[var(--text-secondary)] hover:...">
<X className="w-5 h-5" />
</button>
// ✅ CORRECT - Use shared component
<IconButton onClick={onClose} aria-label="Close">
<X className="w-5 h-5" />
</IconButton>
```
**Patterns to make shared components:**
- Icon buttons (close, edit, delete, etc.)
- Loading/error displays
- Status badges
- Tab switching
- Label + value display (detail screens)
- Search input
- Color legends
**Avoid over-generalization:**
```tsx
// ❌ WRONG - Forcing stepper variant into IconButton
export const iconButtonVariants = cva('...', {
variants: {
variant: {
default: '...',
outlined: '...', // ← Stepper-specific, not used elsewhere
},
size: {
medium: 'p-2',
stepper: 'w-8 h-8', // ← Only used with outlined
},
},
})
// ✅ CORRECT - Purpose-specific component
export function StepperButton(props) {
return (
<button className="w-8 h-8 rounded-full border ..." {...props}>
<Plus className="w-4 h-4" />
</button>
)
}
```
**Signs to make separate components:**
- Implicit constraints like "this variant is always with this size"
- Added variant is clearly different from original component's purpose
- Props specification becomes complex on the usage side
### 5. Abstraction Level Evaluation
**Conditional branch bloat detection:**
| Pattern | Judgment |
|---------|----------|
| Same conditional in 3+ places | Extract to shared component → **REJECT** |
| Props-based branching with 5+ types | Consider component split |
| Nested ternaries in render | Early return or component separation → **REJECT** |
| Type-based render branching | Consider polymorphic components |
**Abstraction level mismatch detection:**
| Pattern | Problem | Fix |
|---------|---------|-----|
| Data fetching logic mixed in JSX | Hard to read | Extract to custom hook |
| Business logic mixed in component | Responsibility violation | Separate to hooks/utils |
| Style calculation logic scattered | Hard to maintain | Extract to utility function |
| Same transformation in multiple places | DRY violation | Extract to common function |
**Good abstraction examples:**
```tsx
// ❌ Conditional bloat
function UserBadge({ user }) {
if (user.role === 'admin') {
return <span className="bg-red-500">Admin</span>
} else if (user.role === 'moderator') {
return <span className="bg-yellow-500">Moderator</span>
} else if (user.role === 'premium') {
return <span className="bg-purple-500">Premium</span>
} else {
return <span className="bg-gray-500">User</span>
}
}
// ✅ Abstracted with Map
const ROLE_CONFIG = {
admin: { label: 'Admin', className: 'bg-red-500' },
moderator: { label: 'Moderator', className: 'bg-yellow-500' },
premium: { label: 'Premium', className: 'bg-purple-500' },
default: { label: 'User', className: 'bg-gray-500' },
}
function UserBadge({ user }) {
const config = ROLE_CONFIG[user.role] ?? ROLE_CONFIG.default
return <span className={config.className}>{config.label}</span>
}
```
```tsx
// ❌ Mixed abstraction levels
function OrderList() {
const [orders, setOrders] = useState([])
useEffect(() => {
fetch('/api/orders')
.then(res => res.json())
.then(data => setOrders(data))
}, [])
return orders.map(order => (
<div>{order.total.toLocaleString()} USD</div>
))
}
// ✅ Aligned abstraction levels
function OrderList() {
const { data: orders } = useOrders() // Hide data fetching
return orders.map(order => (
<OrderItem key={order.id} order={order} />
))
}
```
### 6. Frontend and Backend Separation of Concerns
#### 6.1 Display Format Responsibility
**Principle: Backend returns "data", frontend converts to "display format".**
```tsx
// ✅ Frontend: Convert to display format
export function formatPrice(amount: number): string {
return `$${amount.toLocaleString()}`
}
export function formatDate(date: Date): string {
return format(date, 'MMM d, yyyy')
}
```
**Reasons:**
- Display format is a UI concern, not backend responsibility
- Easy to support internationalization
- Frontend can flexibly change display
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Backend returns display strings | Suggest design review |
| Same format logic copy-pasted | Unify to utility function |
| Inline formatting in component | Extract to function |
#### 6.2 Domain Logic Placement (Smart UI Elimination)
**Principle: Domain logic (business rules) belongs in the backend. Frontend only displays and edits state.**
**What is domain logic:**
- Aggregate business rules (stock validation, price calculation, status transitions)
- Business constraint validation
- Invariant enforcement
**Frontend responsibilities:**
- Display state received from server
- Collect user input and send commands to backend
- Manage UI-only temporary state (focus, hover, modal open/close)
- Display format conversion (formatting, sorting, filtering)
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Price calculation/stock validation in frontend | Move to backend → **REJECT** |
| Status transition rules in frontend | Move to backend → **REJECT** |
| Business validation in frontend | Move to backend → **REJECT** |
| Recalculating server-computable values in frontend | Redundant → **REJECT** |
**Good vs Bad Examples:**
```tsx
// ❌ BAD - Business rules in frontend
function OrderForm({ order }: { order: Order }) {
const totalPrice = order.items.reduce((sum, item) =>
sum + item.price * item.quantity, 0
)
const canCheckout = totalPrice >= 100 && order.items.every(i => i.stock > 0)
return <button disabled={!canCheckout}>Checkout</button>
}
// ✅ GOOD - Display state received from server
function OrderForm({ order }: { order: Order }) {
// totalPrice, canCheckout are received from server
return (
<>
<div>{formatPrice(order.totalPrice)}</div>
<button disabled={!order.canCheckout}>Checkout</button>
</>
)
}
```
```tsx
// ❌ BAD - Status transition logic in frontend
function TaskCard({ task }: { task: Task }) {
const canStart = task.status === 'pending' && task.assignee !== null
const canComplete = task.status === 'in_progress' && /* complex conditions... */
return (
<>
<button onClick={startTask} disabled={!canStart}>Start</button>
<button onClick={completeTask} disabled={!canComplete}>Complete</button>
</>
)
}
// ✅ GOOD - Server returns allowed actions
function TaskCard({ task }: { task: Task }) {
// task.allowedActions = ['start', 'cancel'], etc., calculated by server
const canStart = task.allowedActions.includes('start')
const canComplete = task.allowedActions.includes('complete')
return (
<>
<button onClick={startTask} disabled={!canStart}>Start</button>
<button onClick={completeTask} disabled={!canComplete}>Complete</button>
</>
)
}
```
**Exceptions (OK to have logic in frontend):**
| Case | Reason |
|------|--------|
| UI-only validation | UX feedback like "required field", "max length" (must also validate on server) |
| Client-side filter/sort | Changing display order of lists received from server |
| Display condition branching | UI control like "show details if logged in" |
| Real-time feedback | Preview display during input |
**Decision criteria: "Would the business break if this calculation differs from the server?"**
- YES → Place in backend (domain logic)
- NO → OK in frontend (display logic)
### 7. Performance
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Unnecessary re-renders | Needs optimization |
| Large lists without virtualization | Warning |
| Unoptimized images | Warning |
| Unused code in bundle | Check tree-shaking |
| Excessive memoization | Verify necessity |
**Optimization Checklist:**
- [ ] Are `React.memo` / `useMemo` / `useCallback` appropriate?
- [ ] Are large lists using virtual scroll?
- [ ] Is Code Splitting appropriate?
- [ ] Are images lazy loaded?
**Anti-patterns:**
```tsx
// ❌ New object every render
<Child style={{ color: 'red' }} />
// ✅ Constant or useMemo
const style = useMemo(() => ({ color: 'red' }), []);
<Child style={style} />
```
### 8. Accessibility
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Interactive elements without keyboard support | REJECT |
| Images without alt attribute | REJECT |
| Form elements without labels | REJECT |
| Information conveyed by color only | REJECT |
| Missing focus management (modals, etc.) | REJECT |
**Checklist:**
- [ ] Using semantic HTML?
- [ ] Are ARIA attributes appropriate (not excessive)?
- [ ] Is keyboard navigation possible?
- [ ] Does it make sense with a screen reader?
- [ ] Is color contrast sufficient?
### 9. TypeScript/Type Safety
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Use of `any` type | REJECT |
| Excessive type assertions (as) | Needs review |
| No Props type definition | REJECT |
| Inappropriate event handler types | Needs fix |
### 10. Frontend Security
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| dangerouslySetInnerHTML usage | Check XSS risk |
| Unsanitized user input | REJECT |
| Sensitive data stored in frontend | REJECT |
| CSRF token not used | Needs verification |
### 11. Testability
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| No data-testid, etc. | Warning |
| Structure difficult to test | Consider separation |
| Business logic embedded in UI | REJECT |
### 12. Anti-pattern Detection
**REJECT** if found:
| Anti-pattern | Problem |
|--------------|---------|
| God Component | All features concentrated in one component |
| Prop Drilling | Deep props bucket brigade |
| Inline Styles abuse | Maintainability degradation |
| useEffect hell | Dependencies too complex |
| Premature Optimization | Unnecessary memoization |
| Magic Strings | Hardcoded strings |
| Hidden Dependencies | Child components with hidden API calls |
| Over-generalization | Components forced to be generic |
## Important ## Important
- **Prioritize user experience**: UX over technical correctness - **Prioritize user experience**: UX over technical correctness

158
resources/global/en/personas/security-reviewer.md
View File

@ -30,164 +30,6 @@ Security cannot be retrofitted. It must be built in from the design stage; "we'l
- Write code yourself (only provide feedback and fix suggestions) - Write code yourself (only provide feedback and fix suggestions)
- Review design or code quality (that's Architect's role) - Review design or code quality (that's Architect's role)
## AI-Generated Code: Special Attention
AI-generated code has unique vulnerability patterns.
**Common security issues in AI-generated code:**
| Pattern | Risk | Example |
|---------|------|---------|
| Plausible but dangerous defaults | High | `cors: { origin: '*' }` looks fine but is dangerous |
| Outdated security practices | Medium | Using deprecated encryption, old auth patterns |
| Incomplete validation | High | Validates format but not business rules |
| Over-trusting inputs | Critical | Assumes internal APIs are always safe |
| Copy-paste vulnerabilities | High | Same dangerous pattern repeated in multiple files |
**Require extra scrutiny:**
- Auth/authorization logic (AI tends to miss edge cases)
- Input validation (AI may check syntax but miss semantics)
- Error messages (AI may expose internal details)
- Config files (AI may use dangerous defaults from training data)
## Review Perspectives
### 1. Injection Attacks
**SQL Injection:**
- SQL construction via string concatenation → **REJECT**
- Not using parameterized queries → **REJECT**
- Unsanitized input in ORM raw queries → **REJECT**
```typescript
// NG
db.query(`SELECT * FROM users WHERE id = ${userId}`)
// OK
db.query('SELECT * FROM users WHERE id = ?', [userId])
```
**Command Injection:**
- Unvalidated input in `exec()`, `spawn()` → **REJECT**
- Insufficient escaping in shell command construction → **REJECT**
```typescript
// NG
exec(`ls ${userInput}`)
// OK
execFile('ls', [sanitizedInput])
```
**XSS (Cross-Site Scripting):**
- Unescaped output to HTML/JS → **REJECT**
- Improper use of `innerHTML`, `dangerouslySetInnerHTML` → **REJECT**
- Direct embedding of URL parameters → **REJECT**
### 2. Authentication & Authorization
**Authentication issues:**
- Hardcoded credentials → **Immediate REJECT**
- Plaintext password storage → **Immediate REJECT**
- Weak hash algorithms (MD5, SHA1) → **REJECT**
- Improper session token management → **REJECT**
**Authorization issues:**
- Missing permission checks → **REJECT**
- IDOR (Insecure Direct Object Reference) → **REJECT**
- Privilege escalation possibility → **REJECT**
```typescript
// NG - No permission check
app.get('/user/:id', (req, res) => {
return db.getUser(req.params.id)
})
// OK
app.get('/user/:id', authorize('read:user'), (req, res) => {
if (req.user.id !== req.params.id && !req.user.isAdmin) {
return res.status(403).send('Forbidden')
}
return db.getUser(req.params.id)
})
```
### 3. Data Protection
**Sensitive information exposure:**
- Hardcoded API keys, secrets → **Immediate REJECT**
- Sensitive info in logs → **REJECT**
- Internal info exposure in error messages → **REJECT**
- Committed `.env` files → **REJECT**
**Data validation:**
- Unvalidated input values → **REJECT**
- Missing type checks → **REJECT**
- No size limits set → **REJECT**
### 4. Cryptography
- Use of weak crypto algorithms → **REJECT**
- Fixed IV/Nonce usage → **REJECT**
- Hardcoded encryption keys → **Immediate REJECT**
- No HTTPS (production) → **REJECT**
### 5. File Operations
**Path Traversal:**
- File paths containing user input → **REJECT**
- Insufficient `../` sanitization → **REJECT**
```typescript
// NG
const filePath = path.join(baseDir, userInput)
fs.readFile(filePath)
// OK
const safePath = path.resolve(baseDir, userInput)
if (!safePath.startsWith(path.resolve(baseDir))) {
throw new Error('Invalid path')
}
```
**File Upload:**
- No file type validation → **REJECT**
- No file size limits → **REJECT**
- Allowing executable file uploads → **REJECT**
### 6. Dependencies
- Packages with known vulnerabilities → **REJECT**
- Unmaintained packages → Warning
- Unnecessary dependencies → Warning
### 7. Error Handling
- Stack trace exposure in production → **REJECT**
- Detailed error message exposure → **REJECT**
- Swallowing security events → **REJECT**
### 8. Rate Limiting & DoS Protection
- No rate limiting (auth endpoints) → Warning
- Resource exhaustion attack possibility → Warning
- Infinite loop possibility → **REJECT**
### 9. OWASP Top 10 Checklist
| Category | Check Items |
|----------|-------------|
| A01 Broken Access Control | Authorization checks, CORS config |
| A02 Cryptographic Failures | Encryption, sensitive data protection |
| A03 Injection | SQL, Command, XSS |
| A04 Insecure Design | Security design patterns |
| A05 Security Misconfiguration | Default settings, unnecessary features |
| A06 Vulnerable Components | Dependency vulnerabilities |
| A07 Auth Failures | Authentication mechanisms |
| A08 Software Integrity | Code signing, CI/CD |
| A09 Logging Failures | Security logging |
| A10 SSRF | Server-side requests |
## Important ## Important
**Don't miss anything**: Security vulnerabilities get exploited in production. One oversight can lead to a critical incident. **Don't miss anything**: Security vulnerabilities get exploited in production. One oversight can lead to a critical incident.

4
resources/global/en/pieces/default.yaml
View File

@ -20,6 +20,9 @@ stances:
review: ../stances/review.md review: ../stances/review.md
testing: ../stances/testing.md testing: ../stances/testing.md
knowledge:
architecture: ../knowledge/architecture.md
personas: personas:
planner: ../personas/planner.md planner: ../personas/planner.md
architect-planner: ../personas/architect-planner.md architect-planner: ../personas/architect-planner.md
@ -224,6 +227,7 @@ movements:
edit: false edit: false
persona: architecture-reviewer persona: architecture-reviewer
stance: review stance: review
knowledge: architecture
report: report:
name: 05-architect-review.md name: 05-architect-review.md
format: architecture-review format: architecture-review

8
resources/global/en/pieces/expert-cqrs.yaml
View File

@ -28,6 +28,11 @@ stances:
review: ../stances/review.md review: ../stances/review.md
testing: ../stances/testing.md testing: ../stances/testing.md
knowledge:
frontend: ../knowledge/frontend.md
cqrs-es: ../knowledge/cqrs-es.md
security: ../knowledge/security.md
personas: personas:
planner: ../personas/planner.md planner: ../personas/planner.md
coder: ../personas/coder.md coder: ../personas/coder.md
@ -196,6 +201,7 @@ movements:
edit: false edit: false
persona: cqrs-es-reviewer persona: cqrs-es-reviewer
stance: review stance: review
knowledge: cqrs-es
report: report:
name: 04-cqrs-es-review.md name: 04-cqrs-es-review.md
format: cqrs-es-review format: cqrs-es-review
@ -215,6 +221,7 @@ movements:
edit: false edit: false
persona: frontend-reviewer persona: frontend-reviewer
stance: review stance: review
knowledge: frontend
report: report:
name: 05-frontend-review.md name: 05-frontend-review.md
format: frontend-review format: frontend-review
@ -234,6 +241,7 @@ movements:
edit: false edit: false
persona: security-reviewer persona: security-reviewer
stance: review stance: review
knowledge: security
report: report:
name: 06-security-review.md name: 06-security-review.md
format: security-review format: security-review

8
resources/global/en/pieces/expert.yaml
View File

@ -28,6 +28,11 @@ stances:
review: ../stances/review.md review: ../stances/review.md
testing: ../stances/testing.md testing: ../stances/testing.md
knowledge:
frontend: ../knowledge/frontend.md
security: ../knowledge/security.md
architecture: ../knowledge/architecture.md
personas: personas:
planner: ../personas/planner.md planner: ../personas/planner.md
coder: ../personas/coder.md coder: ../personas/coder.md
@ -195,6 +200,7 @@ movements:
edit: false edit: false
persona: architecture-reviewer persona: architecture-reviewer
stance: review stance: review
knowledge: architecture
report: report:
name: 04-architect-review.md name: 04-architect-review.md
format: architecture-review format: architecture-review
@ -214,6 +220,7 @@ movements:
edit: false edit: false
persona: frontend-reviewer persona: frontend-reviewer
stance: review stance: review
knowledge: frontend
report: report:
name: 05-frontend-review.md name: 05-frontend-review.md
format: frontend-review format: frontend-review
@ -233,6 +240,7 @@ movements:
edit: false edit: false
persona: security-reviewer persona: security-reviewer
stance: review stance: review
knowledge: security
report: report:
name: 06-security-review.md name: 06-security-review.md
format: security-review format: security-review

0
resources/global/ja/knowledge/.gitkeep
View File

427
resources/global/ja/knowledge/architecture.md Normal file
View File

@ -0,0 +1,427 @@
# アーキテクチャ知識
## 構造・設計
**ファイル分割**
| 基準 | 判定 |
|--------------|------|
| 1ファイル200行超 | 分割を検討 |
| 1ファイル300行超 | REJECT |
| 1ファイルに複数の責務 | REJECT |
| 関連性の低いコードが同居 | REJECT |
**モジュール構成**
- 高凝集: 関連する機能がまとまっているか
- 低結合: モジュール間の依存が最小限か
- 循環依存がないか
- 適切なディレクトリ階層か
**関数設計**
- 1関数1責務になっているか
- 30行を超える関数は分割を検討
- 副作用が明確か
**レイヤー設計**
- 依存の方向: 上位層 → 下位層（逆方向禁止）
- Controller → Service → Repository の流れが守られているか
- 1インターフェース = 1責務（巨大なServiceクラス禁止）
**ディレクトリ構造**
構造パターンの選択:
| パターン | 適用場面 | 例 |
|---------|---------|-----|
| レイヤード | 小規模、CRUD中心 | `controllers/`, `services/`, `repositories/` |
| Vertical Slice | 中〜大規模、機能独立性が高い | `features/auth/`, `features/order/` |
| ハイブリッド | 共通基盤 + 機能モジュール | `core/` + `features/` |
Vertical Slice Architecture（機能単位でコードをまとめる構造）:
```
src/
├── features/
│ ├── auth/
│ │ ├── LoginCommand.ts
│ │ ├── LoginHandler.ts
│ │ ├── AuthRepository.ts
│ │ └── auth.test.ts
│ └── order/
│ ├── CreateOrderCommand.ts
│ ├── CreateOrderHandler.ts
│ └── ...
└── shared/ # 複数featureで共有
├── database/
└── middleware/
```
Vertical Slice の判定基準:
| 基準 | 判定 |
|------|------|
| 1機能が3ファイル以上のレイヤーに跨る | Slice化を検討 |
| 機能間の依存がほぼない | Slice化推奨 |
| 共通処理が50%以上 | レイヤード維持 |
| チームが機能別に分かれている | Slice化必須 |
禁止パターン:
| パターン | 問題 |
|---------|------|
| `utils/` の肥大化 | 責務不明の墓場になる |
| `common/` への安易な配置 | 依存関係が不明確になる |
| 深すぎるネスト（4階層超） | ナビゲーション困難 |
| 機能とレイヤーの混在 | `features/services/` は禁止 |
**責務の分離**
- 読み取りと書き込みの責務が分かれているか
- データ取得はルート（View/Controller）で行い、子に渡しているか
- エラーハンドリングが一元化されているか（各所でtry-catch禁止）
- ビジネスロジックがController/Viewに漏れていないか
## コード品質の検出手法
**説明コメント（What/How）の検出基準**
コードの動作をそのまま言い換えているコメントを検出する。
| 判定 | 基準 |
|------|------|
| REJECT | コードの動作をそのまま自然言語で言い換えている |
| REJECT | 関数名・変数名から明らかなことを繰り返している |
| REJECT | JSDocが関数名の言い換えだけで情報を追加していない |
| OK | なぜその実装を選んだかの設計判断を説明している |
| OK | 一見不自然に見える挙動の理由を説明している |
| 最良 | コメントなしでコード自体が意図を語っている |
```typescript
// REJECT - コードの言い換え（What）
// If interrupted, abort immediately
if (status === 'interrupted') {
return ABORT_STEP;
}
// REJECT - ループの存在を言い換えただけ
// Check transitions in order
for (const transition of step.transitions) {
// REJECT - 関数名の繰り返し
/** Check if status matches transition condition. */
export function matchesCondition(status: Status, condition: TransitionCondition): boolean {
// OK - 設計判断の理由（Why）
// ユーザー中断はピース定義のトランジションより優先する
if (status === 'interrupted') {
return ABORT_STEP;
}
// OK - 一見不自然な挙動の理由
// stay はループを引き起こす可能性があるが、ユーザーが明示的に指定した場合のみ使われる
return step.name;
```
**状態の直接変更の検出基準**
配列やオブジェクトの直接変更（ミューテーション）を検出する。
```typescript
// REJECT - 配列の直接変更
const steps: Step[] = getSteps();
steps.push(newStep); // 元の配列を破壊
steps.splice(index, 1); // 元の配列を破壊
steps[0].status = 'done'; // ネストされたオブジェクトも直接変更
// OK - イミュータブルな操作
const withNew = [...steps, newStep];
const without = steps.filter((_, i) => i !== index);
const updated = steps.map((s, i) =>
i === 0 ? { ...s, status: 'done' } : s
);
// REJECT - オブジェクトの直接変更
function updateConfig(config: Config) {
config.logLevel = 'debug'; // 引数を直接変更
config.steps.push(newStep); // ネストも直接変更
return config;
}
// OK - 新しいオブジェクトを返す
function updateConfig(config: Config): Config {
return {
...config,
logLevel: 'debug',
steps: [...config.steps, newStep],
};
}
```
## セキュリティ（基本チェック）
- インジェクション対策（SQL, コマンド, XSS）
- ユーザー入力の検証
- 機密情報のハードコーディング
## テスタビリティ
- 依存性注入が可能な設計か
- モック可能か
- テストが書かれているか
## アンチパターン検出
以下のパターンを見つけたら REJECT:
| アンチパターン | 問題 |
|---------------|------|
| God Class/Component | 1つのクラスが多くの責務を持っている |
| Feature Envy | 他モジュールのデータを頻繁に参照している |
| Shotgun Surgery | 1つの変更が複数ファイルに波及する構造 |
| 過度な汎用化 | 今使わないバリアントや拡張ポイント |
| 隠れた依存 | 子コンポーネントが暗黙的にAPIを呼ぶ等 |
| 非イディオマティック | 言語・FWの作法を無視した独自実装 |
## 抽象化レベルの評価
**条件分岐の肥大化検出**
| パターン | 判定 |
|---------|------|
| 同じif-elseパターンが3箇所以上 | ポリモーフィズムで抽象化 → REJECT |
| switch/caseが5分岐以上 | Strategy/Mapパターンを検討 |
| フラグ引数で挙動を変える | 別関数に分割 → REJECT |
| 型による分岐（instanceof/typeof） | ポリモーフィズムに置換 → REJECT |
| ネストした条件分岐（3段以上） | 早期リターンまたは抽出 → REJECT |
**抽象度の不一致検出**
| パターン | 問題 | 修正案 |
|---------|------|--------|
| 高レベル処理の中に低レベル詳細 | 読みにくい | 詳細を関数に抽出 |
| 1関数内で抽象度が混在 | 認知負荷 | 同じ粒度に揃える |
| ビジネスロジックにDB操作が混在 | 責務違反 | Repository層に分離 |
| 設定値と処理ロジックが混在 | 変更困難 | 設定を外部化 |
**良い抽象化の例**
```typescript
// 条件分岐の肥大化
function process(type: string) {
if (type === 'A') { /* 処理A */ }
else if (type === 'B') { /* 処理B */ }
else if (type === 'C') { /* 処理C */ }
// ...続く
}
// Mapパターンで抽象化
const processors: Record<string, () => void> = {
A: processA,
B: processB,
C: processC,
};
function process(type: string) {
processors[type]?.();
}
```
```typescript
// 抽象度の混在
function createUser(data: UserData) {
// 高レベル: ビジネスロジック
validateUser(data);
// 低レベル: DB操作の詳細
const conn = await pool.getConnection();
await conn.query('INSERT INTO users...');
conn.release();
}
// 抽象度を揃える
function createUser(data: UserData) {
validateUser(data);
await userRepository.save(data); // 詳細は隠蔽
}
```
## その場しのぎの検出
「とりあえず動かす」ための妥協を見逃さない。
| パターン | 例 |
|---------|-----|
| 不要なパッケージ追加 | 動かすためだけに入れた謎のライブラリ |
| テストの削除・スキップ | `@Disabled`、`.skip()`、コメントアウト |
| 空実装・スタブ放置 | `return null`、`// TODO: implement`、`pass` |
| モックデータの本番混入 | ハードコードされたダミーデータ |
| エラー握りつぶし | 空の `catch {}`、`rescue nil` |
| マジックナンバー | 説明なしの `if (status == 3)` |
## TODOコメントの厳格な禁止
「将来やる」は決してやらない。今やらないことは永遠にやらない。
TODOコメントは即REJECT。
```kotlin
// REJECT - 将来を見越したTODO
// TODO: 施設IDによる認可チェックを追加
fun deleteCustomHoliday(@PathVariable id: String) {
deleteCustomHolidayInputPort.execute(input)
}
// APPROVE - 今実装する
fun deleteCustomHoliday(@PathVariable id: String) {
val currentUserFacilityId = getCurrentUserFacilityId()
val holiday = findHolidayById(id)
require(holiday.facilityId == currentUserFacilityId) {
"Cannot delete holiday from another facility"
}
deleteCustomHolidayInputPort.execute(input)
}
```
TODOが許容される唯一のケース:
| 条件 | 例 | 判定 |
|------|-----|------|
| 外部依存で今は実装不可 + Issue化済み | `// TODO(#123): APIキー取得後に実装` | 許容 |
| 技術的制約で回避不可 + Issue化済み | `// TODO(#456): ライブラリバグ修正待ち` | 許容 |
| 「将来実装」「後で追加」 | `// TODO: バリデーション追加` | REJECT |
| 「時間がないので」 | `// TODO: リファクタリング` | REJECT |
正しい対処:
- 今必要 → 今実装する
- 今不要 → コードを削除する
- 外部要因で不可 → Issue化してチケット番号をコメントに入れる
## DRY違反の検出
重複コードを検出する。
| パターン | 判定 |
|---------|------|
| 同じロジックが3箇所以上 | 即REJECT - 関数/メソッドに抽出 |
| 同じバリデーションが2箇所以上 | 即REJECT - バリデーター関数に抽出 |
| 似たようなコンポーネントが3個以上 | 即REJECT - 共通コンポーネント化 |
| コピペで派生したコード | 即REJECT - パラメータ化または抽象化 |
AHA原則（Avoid Hasty Abstractions）とのバランス:
- 2回の重複 → 様子見
- 3回の重複 → 即抽出
- ドメインが異なる重複 → 抽象化しない（例: 顧客用バリデーションと管理者用バリデーションは別物）
## 仕様準拠の検証
変更が、プロジェクトの文書化された仕様に準拠しているか検証する。
検証対象:
| 対象 | 確認内容 |
|------|---------|
| CLAUDE.md / README.md | スキーマ定義、設計原則、制約に従っているか |
| 型定義・Zodスキーマ | 新しいフィールドがスキーマに反映されているか |
| YAML/JSON設定ファイル | 文書化されたフォーマットに従っているか |
具体的なチェック:
1. 設定ファイル（YAML等）を変更・追加した場合:
- CLAUDE.md等に記載されたスキーマ定義と突合する
- 無視されるフィールドや無効なフィールドが含まれていないか
- 必須フィールドが欠落していないか
2. 型定義やインターフェースを変更した場合:
- ドキュメントのスキーマ説明が更新されているか
- 既存の設定ファイルが新しいスキーマと整合するか
このパターンを見つけたら REJECT:
| パターン | 問題 |
|---------|------|
| 仕様に存在しないフィールドの使用 | 無視されるか予期しない動作 |
| 仕様上無効な値の設定 | 実行時エラーまたは無視される |
| 文書化された制約への違反 | 設計意図に反する |
## 呼び出しチェーン検証
新しいパラメータ・フィールドが追加された場合、変更ファイル内だけでなく呼び出し元も検証する。
検証手順:
1. 新しいオプショナルパラメータや interface フィールドを見つけたら、`Grep` で全呼び出し元を検索
2. 全呼び出し元が新しいパラメータを渡しているか確認
3. フォールバック値（`?? default`）がある場合、フォールバックが使われるケースが意図通りか確認
危険パターン:
| パターン | 問題 | 検出方法 |
|---------|------|---------|
| `options.xxx ?? fallback` で全呼び出し元が `xxx` を省略 | 機能が実装されているのに常にフォールバック | grep で呼び出し元を確認 |
| テストがモックで直接値をセット | 実際の呼び出しチェーンを経由しない | テストの構築方法を確認 |
| `executeXxx()` が内部で使う `options` を引数で受け取らない | 上位から値を渡す口がない | 関数シグネチャを確認 |
```typescript
// 配線漏れ: projectCwd を受け取る口がない
export async function executePiece(config, cwd, task) {
const engine = new PieceEngine(config, cwd, task); // options なし
}
// 配線済み: projectCwd を渡せる
export async function executePiece(config, cwd, task, options?) {
const engine = new PieceEngine(config, cwd, task, options);
}
```
呼び出し元の制約による論理的デッドコード:
呼び出しチェーンの検証は「配線漏れ」だけでなく、逆方向——呼び出し元が既に保証している条件に対する不要な防御コード——にも適用する。
| パターン | 問題 | 検出方法 |
|---------|------|---------|
| 呼び出し元がTTY必須なのに関数内でTTYチェック | 到達しない分岐が残る | grep で全呼び出し元の前提条件を確認 |
| 呼び出し元がnullチェック済みなのに再度nullガード | 冗長な防御 | 呼び出し元の制約を追跡 |
| 呼び出し元が型で制約しているのにランタイムチェック | 型安全を信頼していない | TypeScriptの型制約を確認 |
検証手順:
1. 防御的な条件分岐（TTYチェック、nullガード等）を見つけたら、grep で全呼び出し元を確認
2. 全呼び出し元がその条件を既に保証しているなら、防御は不要 → REJECT
3. 一部の呼び出し元が保証していない場合は、防御を残す
## 品質特性
| 特性 | 確認観点 |
|------|---------|
| Scalability | 負荷増加に対応できる設計か |
| Maintainability | 変更・修正が容易か |
| Observability | ログ・監視が可能な設計か |
## 大局観
細かい「クリーンコード」の指摘に終始しない。
確認すべきこと:
- このコードは将来どう変化するか
- スケーリングの必要性は考慮されているか
- 技術的負債を生んでいないか
- ビジネス要件と整合しているか
- 命名がドメインと一貫しているか
## 変更スコープの評価
変更スコープを確認し、レポートに記載する（ブロッキングではない）。
| スコープサイズ | 変更行数 | 対応 |
|---------------|---------|------|
| Small | 〜200行 | そのままレビュー |
| Medium | 200-500行 | そのままレビュー |
| Large | 500行以上 | レビューは継続。分割可能か提案を付記 |
大きな変更が必要なタスクもある。行数だけでREJECTしない。
確認すること:
- 変更が論理的にまとまっているか（無関係な変更が混在していないか）
- Coderのスコープ宣言と実際の変更が一致しているか
提案として記載すること（ブロッキングではない）:
- 分割可能な場合は分割案を提示

417
resources/global/ja/knowledge/cqrs-es.md Normal file
View File

@ -0,0 +1,417 @@
# CQRS+ES知識
## Aggregate設計
Aggregateは判断に必要なフィールドのみ保持する。
Command Model（Aggregate）の役割は「コマンドを受けて判断し、イベントを発行する」こと。クエリ用データはRead Model（Projection）が担当する。
「判断に必要」とは:
- `if`/`require`の条件分岐に使う
- インスタンスメソッドでイベント発行時にフィールド値を参照する
| 基準 | 判定 |
|------|------|
| Aggregateが複数のトランザクション境界を跨ぐ | REJECT |
| Aggregate間の直接参照（ID参照でない） | REJECT |
| Aggregateが100行を超える | 分割を検討 |
| ビジネス不変条件がAggregate外にある | REJECT |
| 判断に使わないフィールドを保持 | REJECT |
良いAggregate:
```kotlin
// 判断に必要なフィールドのみ
data class Order(
val orderId: String, // イベント発行時に使用
val status: OrderStatus // 状態チェックに使用
) {
fun confirm(confirmedBy: String): OrderConfirmedEvent {
require(status == OrderStatus.PENDING) { "確定できる状態ではありません" }
return OrderConfirmedEvent(
orderId = orderId,
confirmedBy = confirmedBy,
confirmedAt = LocalDateTime.now()
)
}
}
// 判断に使わないフィールドを保持（NG）
data class Order(
val orderId: String,
val customerId: String, // 判断に未使用
val shippingAddress: Address, // 判断に未使用
val status: OrderStatus
)
```
追加操作がないAggregateはIDのみ:
```kotlin
// 作成のみで追加操作がない場合
data class Notification(val notificationId: String) {
companion object {
fun create(customerId: String, message: String): NotificationCreatedEvent {
return NotificationCreatedEvent(
notificationId = UUID.randomUUID().toString(),
customerId = customerId,
message = message
)
}
}
}
```
## イベント設計
| 基準 | 判定 |
|------|------|
| イベントが過去形でない（Created → Create） | REJECT |
| イベントにロジックが含まれる | REJECT |
| イベントが他Aggregateの内部状態を含む | REJECT |
| イベントのスキーマがバージョン管理されていない | 警告 |
| CRUDスタイルのイベント（Updated, Deleted） | 要検討 |
良いイベント:
```kotlin
// Good: ドメインの意図が明確
OrderPlaced, PaymentReceived, ItemShipped
// Bad: CRUDスタイル
OrderUpdated, OrderDeleted
```
イベント粒度:
- 細かすぎ: `OrderFieldChanged` → ドメインの意図が不明
- 適切: `ShippingAddressChanged` → 意図が明確
- 粗すぎ: `OrderModified` → 何が変わったか不明
## コマンドハンドラ
| 基準 | 判定 |
|------|------|
| ハンドラがDBを直接操作 | REJECT |
| ハンドラが複数Aggregateを変更 | REJECT |
| コマンドのバリデーションがない | REJECT |
| ハンドラがクエリを実行して判断 | 要検討 |
良いコマンドハンドラ:
```
1. コマンドを受け取る
2. Aggregateをイベントストアから復元
3. Aggregateにコマンドを適用
4. 発行されたイベントを保存
```
## プロジェクション設計
| 基準 | 判定 |
|------|------|
| プロジェクションがコマンドを発行 | REJECT |
| プロジェクションがWriteモデルを参照 | REJECT |
| 複数のユースケースを1つのプロジェクションで賄う | 要検討 |
| リビルド不可能な設計 | REJECT |
良いプロジェクション:
- 特定の読み取りユースケースに最適化
- イベントから冪等に再構築可能
- Writeモデルから完全に独立
## Query側の設計
ControllerはQueryGatewayを使う。Repositoryを直接使わない。
レイヤー間の型:
- `application/query/` - Query結果の型（例: `OrderDetail`）
- `adapter/protocol/` - RESTレスポンスの型（例: `OrderDetailResponse`）
- QueryHandlerはapplication層の型を返し、Controllerがadapter層の型に変換
```kotlin
// application/query/OrderDetail.kt
data class OrderDetail(
val orderId: String,
val customerName: String,
val totalAmount: Money
)
// adapter/protocol/OrderDetailResponse.kt
data class OrderDetailResponse(...) {
companion object {
fun from(detail: OrderDetail) = OrderDetailResponse(...)
}
}
// QueryHandler - application層の型を返す
@QueryHandler
fun handle(query: GetOrderDetailQuery): OrderDetail? {
val entity = repository.findById(query.id) ?: return null
return OrderDetail(...)
}
// Controller - adapter層の型に変換
@GetMapping("/{id}")
fun getById(@PathVariable id: String): ResponseEntity<OrderDetailResponse> {
val detail = queryGateway.query(
GetOrderDetailQuery(id),
OrderDetail::class.java
).join() ?: throw NotFoundException("...")
return ResponseEntity.ok(OrderDetailResponse.from(detail))
}
```
構成:
```
Controller (adapter) → QueryGateway → QueryHandler (application) → Repository
↓ ↓
Response.from(detail) OrderDetail
```
## 結果整合性
| 状況 | 対応 |
|------|------|
| UIが即座に更新を期待している | 設計見直し or ポーリング/WebSocket |
| 整合性遅延が許容範囲を超える | アーキテクチャ再検討 |
| 補償トランザクションが未定義 | 障害シナリオの検討を要求 |
## Saga vs EventHandler
Sagaは「競合が発生する複数アグリゲート間の操作」にのみ使用する。
Sagaが必要なケース:
```
複数のアクターが同じリソースを取り合う場合
例: 在庫確保（10人が同時に同じ商品を注文）
OrderPlacedEvent
↓ InventoryReservationSaga
ReserveInventoryCommand → Inventory集約（同時実行を直列化）
↓
InventoryReservedEvent → ConfirmOrderCommand
InventoryReservationFailedEvent → CancelOrderCommand
```
Sagaが不要なケース:
```
競合が発生しない操作
例: 注文キャンセル時の在庫解放
OrderCancelledEvent
↓ InventoryReleaseHandler（単純なEventHandler）
ReleaseInventoryCommand
↓
InventoryReleasedEvent
```
判断基準:
| 状況 | Saga | EventHandler |
|------|------|--------------|
| リソースの取り合いがある | 使う | - |
| 補償トランザクションが必要 | 使う | - |
| 競合しない単純な連携 | - | 使う |
| 失敗時は再試行で十分 | - | 使う |
アンチパターン:
```kotlin
// NG - ライフサイクル管理のためにSagaを使う
@Saga
class OrderLifecycleSaga {
// 注文の全状態遷移をSagaで追跡
// PLACED → CONFIRMED → SHIPPED → DELIVERED
}
// OK - 結果整合性が必要な操作だけをSagaで処理
@Saga
class InventoryReservationSaga {
// 在庫確保の同時実行制御のみ
}
```
Sagaはライフサイクル管理ツールではない。結果整合性が必要な「操作」単位で作成する。
## 例外 vs イベント（失敗時の選択）
監査不要な失敗は例外、監査が必要な失敗はイベント。
例外アプローチ（推奨: ほとんどのケース）:
```kotlin
// ドメインモデル: バリデーション失敗時に例外をスロー
fun reserveInventory(orderId: String, quantity: Int): InventoryReservedEvent {
if (availableQuantity < quantity) {
throw InsufficientInventoryException("在庫が不足しています")
}
return InventoryReservedEvent(productId, orderId, quantity)
}
// Saga: exceptionally でキャッチして補償アクション
commandGateway.send<Any>(command)
.exceptionally { ex ->
commandGateway.send<Any>(CancelOrderCommand(
orderId = orderId,
reason = ex.cause?.message ?: "在庫確保に失敗しました"
))
null
}
```
イベントアプローチ（稀なケース）:
```kotlin
// 監査が必要な場合のみ
data class PaymentFailedEvent(
val paymentId: String,
val reason: String,
val attemptedAmount: Money
) : PaymentEvent
```
判断基準:
| 質問 | 例外 | イベント |
|------|------|----------|
| この失敗を後で確認する必要があるか? | No | Yes |
| 規制やコンプライアンスで記録が必要か? | No | Yes |
| Sagaだけが失敗を気にするか? | Yes | No |
| Event Storeに残すと価値があるか? | No | Yes |
デフォルトは例外アプローチ。監査要件がある場合のみイベントを検討する。
## 抽象化レベルの評価
**条件分岐の肥大化検出**
| パターン | 判定 |
|---------|------|
| 同じif-elseパターンが3箇所以上 | ポリモーフィズムで抽象化 → REJECT |
| switch/caseが5分岐以上 | Strategy/Mapパターンを検討 |
| イベント種別による分岐が増殖 | イベントハンドラを分離 → REJECT |
| Aggregate内の状態分岐が複雑 | State Patternを検討 |
**抽象度の不一致検出**
| パターン | 問題 | 修正案 |
|---------|------|--------|
| CommandHandlerにDB操作詳細 | 責務違反 | Repository層に分離 |
| EventHandlerにビジネスロジック | 責務違反 | ドメインサービスに抽出 |
| Aggregateに永続化処理 | レイヤー違反 | EventStore経由に変更 |
| Projectionに計算ロジック | 保守困難 | 専用サービスに抽出 |
良い抽象化の例:
```kotlin
// イベント種別による分岐の増殖（NG）
@EventHandler
fun on(event: DomainEvent) {
when (event) {
is OrderPlacedEvent -> handleOrderPlaced(event)
is OrderConfirmedEvent -> handleOrderConfirmed(event)
is OrderShippedEvent -> handleOrderShipped(event)
// ...どんどん増える
}
}
// イベントごとにハンドラを分離（OK）
@EventHandler
fun on(event: OrderPlacedEvent) { ... }
@EventHandler
fun on(event: OrderConfirmedEvent) { ... }
@EventHandler
fun on(event: OrderShippedEvent) { ... }
```
```kotlin
// 状態による分岐が複雑（NG）
fun process(command: ProcessCommand) {
when (status) {
PENDING -> if (command.type == "approve") { ... } else if (command.type == "reject") { ... }
APPROVED -> if (command.type == "ship") { ... }
// ...複雑化
}
}
// State Patternで抽象化（OK）
sealed class OrderState {
abstract fun handle(command: ProcessCommand): List<DomainEvent>
}
class PendingState : OrderState() {
override fun handle(command: ProcessCommand) = when (command) {
is ApproveCommand -> listOf(OrderApprovedEvent(...))
is RejectCommand -> listOf(OrderRejectedEvent(...))
else -> throw InvalidCommandException()
}
}
```
## アンチパターン検出
以下を見つけたら REJECT:
| アンチパターン | 問題 |
|---------------|------|
| CRUD偽装 | CQRSの形だけ真似てCRUD実装 |
| Anemic Domain Model | Aggregateが単なるデータ構造 |
| Event Soup | 意味のないイベントが乱発される |
| Temporal Coupling | イベント順序に暗黙の依存 |
| Missing Events | 重要なドメインイベントが欠落 |
| God Aggregate | 1つのAggregateに全責務が集中 |
## テスト戦略
レイヤーごとにテスト方針を分ける。
テストピラミッド:
```
┌─────────────┐
│ E2E Test │ ← 少数: 全体フロー確認
├─────────────┤
│ Integration │ ← Command→Event→Projection→Query の連携確認
├─────────────┤
│ Unit Test │ ← 多数: 各レイヤー独立テスト
└─────────────┘
```
Command側（Aggregate）:
```kotlin
// AggregateTestFixture使用
@Test
fun `確定コマンドでイベントが発行される`() {
fixture
.given(OrderPlacedEvent(...))
.`when`(ConfirmOrderCommand(orderId, confirmedBy))
.expectSuccessfulHandlerExecution()
.expectEvents(OrderConfirmedEvent(...))
}
```
Query側:
```kotlin
// Read Model直接セットアップ + QueryGateway
@Test
fun `注文詳細が取得できる`() {
// Given: Read Modelを直接セットアップ
orderRepository.save(OrderEntity(...))
// When: QueryGateway経由でクエリ実行
val detail = queryGateway.query(GetOrderDetailQuery(orderId), ...).join()
// Then
assertEquals(expectedDetail, detail)
}
```
チェック項目:
| 観点 | 判定 |
|------|------|
| Aggregateテストが状態ではなくイベントを検証している | 必須 |
| Query側テストがCommand経由でデータを作っていない | 推奨 |
| 統合テストでAxonの非同期処理を考慮している | 必須 |
## インフラ層
確認事項:
- イベントストアの選択は適切か
- メッセージング基盤は要件を満たすか
- スナップショット戦略は定義されているか
- イベントのシリアライズ形式は適切か

497
resources/global/ja/knowledge/frontend.md Normal file
View File

@ -0,0 +1,497 @@
# フロントエンド専門知識
## コンポーネント設計
1ファイルにベタ書きしない。必ずコンポーネント分割する。
分離が必須なケース:
- 独自のstateを持つ → 必ず分離
- 50行超のJSX → 分離
- 再利用可能 → 分離
- 責務が複数 → 分離
- ページ内の独立したセクション → 分離
| 基準 | 判定 |
|------|------|
| 1コンポーネント200行超 | 分割を検討 |
| 1コンポーネント300行超 | REJECT |
| 表示とロジックが混在 | 分離を検討 |
| Props drilling（3階層以上） | 状態管理の導入を検討 |
| 複数の責務を持つコンポーネント | REJECT |
良いコンポーネント:
- 単一責務: 1つのことをうまくやる
- 自己完結: 必要な依存が明確
- テスト可能: 副作用が分離されている
コンポーネント分類:
| 種類 | 責務 | 例 |
|------|------|-----|
| Container | データ取得・状態管理 | `UserListContainer` |
| Presentational | 表示のみ | `UserCard` |
| Layout | 配置・構造 | `PageLayout`, `Grid` |
| Utility | 共通機能 | `ErrorBoundary`, `Portal` |
ディレクトリ構成:
```
features/{feature-name}/
├── components/
│ ├── {feature}-view.tsx # メインビュー（子を組み合わせる）
│ ├── {sub-component}.tsx # サブコンポーネント
│ └── index.ts
├── hooks/
├── types.ts
└── index.ts
```
## 状態管理
子コンポーネントは自身で状態を変更しない。イベントを親にバブリングし、親が状態を操作する。
```tsx
// 子が自分で状態を変更（NG）
const ChildBad = ({ initialValue }: { initialValue: string }) => {
const [value, setValue] = useState(initialValue)
return <input value={value} onChange={e => setValue(e.target.value)} />
}
// 親が状態を管理、子はコールバックで通知（OK）
const ChildGood = ({ value, onChange }: { value: string; onChange: (v: string) => void }) => {
return <input value={value} onChange={e => onChange(e.target.value)} />
}
const Parent = () => {
const [value, setValue] = useState('')
return <ChildGood value={value} onChange={setValue} />
}
```
例外（子がローカルstate持ってOK）:
- UI専用の一時状態（ホバー、フォーカス、アニメーション）
- 親に伝える必要がない完全にローカルな状態
| 基準 | 判定 |
|------|------|
| 不要なグローバル状態 | ローカル化を検討 |
| 同じ状態が複数箇所で管理 | 正規化が必要 |
| 子から親への状態変更（逆方向データフロー） | REJECT |
| APIレスポンスをそのまま状態に | 正規化を検討 |
| useEffectの依存配列が不適切 | REJECT |
状態配置の判断基準:
| 状態の性質 | 推奨配置 |
|-----------|---------|
| UIの一時的な状態（モーダル開閉等） | ローカル（useState） |
| フォームの入力値 | ローカル or フォームライブラリ |
| 複数コンポーネントで共有 | Context or 状態管理ライブラリ |
| サーバーデータのキャッシュ | TanStack Query等のデータフェッチライブラリ |
## データ取得
API呼び出しはルート（View）コンポーネントで行い、子コンポーネントにはpropsで渡す。
```tsx
// CORRECT - ルートでデータ取得、子に渡す
const OrderDetailView = () => {
const { data: order, isLoading, error } = useGetOrder(orderId)
const { data: items } = useListOrderItems(orderId)
if (isLoading) return <Skeleton />
if (error) return <ErrorDisplay error={error} />
return (
<OrderSummary
order={order}
items={items}
onItemSelect={handleItemSelect}
/>
)
}
// WRONG - 子コンポーネントが自分でデータ取得
const OrderSummary = ({ orderId }) => {
const { data: order } = useGetOrder(orderId)
// ...
}
```
UIの状態変更でパラメータが変わる場合（週切り替え、フィルタ等）:
状態もViewレベルで管理し、コンポーネントにはコールバックを渡す。
```tsx
// CORRECT - 状態もViewで管理
const ScheduleView = () => {
const [currentWeek, setCurrentWeek] = useState(startOfWeek(new Date()))
const { data } = useListSchedules({
from: format(currentWeek, 'yyyy-MM-dd'),
to: format(endOfWeek(currentWeek), 'yyyy-MM-dd'),
})
return (
<WeeklyCalendar
schedules={data?.items ?? []}
currentWeek={currentWeek}
onWeekChange={setCurrentWeek}
/>
)
}
// WRONG - コンポーネント内で状態管理+データ取得
const WeeklyCalendar = ({ facilityId }) => {
const [currentWeek, setCurrentWeek] = useState(...)
const { data } = useListSchedules({ facilityId, from, to })
// ...
}
```
例外（コンポーネント内フェッチが許容されるケース）:
| ケース | 理由 |
|--------|------|
| 無限スクロール | スクロール位置というUI内部状態に依存 |
| 検索オートコンプリート | 入力値に依存したリアルタイム検索 |
| 独立したウィジェット | 通知バッジ、天気等。親のデータと完全に無関係 |
| リアルタイム更新 | WebSocket/Pollingでの自動更新 |
| モーダル内の詳細取得 | 開いたときだけ追加データを取得 |
判断基準: 「親が管理する意味がない / 親に影響を与えない」ケースのみ許容。
| 基準 | 判定 |
|------|------|
| コンポーネント内で直接fetch | Container層に分離 |
| エラーハンドリングなし | REJECT |
| ローディング状態の未処理 | REJECT |
| キャンセル処理なし | 警告 |
| N+1クエリ的なフェッチ | REJECT |
## 共有コンポーネントと抽象化
同じパターンのUIは共有コンポーネント化する。インラインスタイルのコピペは禁止。
```tsx
// WRONG - インラインスタイルのコピペ
<button className="p-2 text-[var(--text-secondary)] hover:...">
<X className="w-5 h-5" />
</button>
// CORRECT - 共有コンポーネント使用
<IconButton onClick={onClose} aria-label="閉じる">
<X className="w-5 h-5" />
</IconButton>
```
共有コンポーネント化すべきパターン:
- アイコンボタン（閉じる、編集、削除等）
- ローディング/エラー表示
- ステータスバッジ
- タブ切り替え
- ラベル+値の表示（詳細画面）
- 検索入力
- カラー凡例
過度な汎用化を避ける:
```tsx
// WRONG - IconButtonに無理やりステッパー用バリアントを追加
export const iconButtonVariants = cva('...', {
variants: {
variant: {
default: '...',
outlined: '...', // ステッパー専用、他で使わない
},
size: {
medium: 'p-2',
stepper: 'w-8 h-8', // outlinedとセットでしか使わない
},
},
})
// CORRECT - 用途別に専用コンポーネント
export function StepperButton(props) {
return (
<button className="w-8 h-8 rounded-full border ..." {...props}>
<Plus className="w-4 h-4" />
</button>
)
}
```
別コンポーネントにすべきサイン:
- 「このvariantはこのsizeとセット」のような暗黙の制約がある
- 追加したvariantが元のコンポーネントの用途と明らかに違う
- 使う側のprops指定が複雑になる
## 抽象化レベルの評価
### 条件分岐の肥大化検出
| パターン | 判定 |
|---------|------|
| 同じ条件分岐が3箇所以上 | 共通コンポーネントに抽出 → REJECT |
| propsによる分岐が5種類以上 | コンポーネント分割を検討 |
| render内の三項演算子のネスト | 早期リターンまたはコンポーネント分離 → REJECT |
| 型による分岐レンダリング | ポリモーフィックコンポーネントを検討 |
### 抽象度の不一致検出
| パターン | 問題 | 修正案 |
|---------|------|--------|
| データ取得ロジックがJSXに混在 | 読みにくい | カスタムフックに抽出 |
| ビジネスロジックがコンポーネントに混在 | 責務違反 | hooks/utilsに分離 |
| スタイル計算ロジックが散在 | 保守困難 | ユーティリティ関数に抽出 |
| 同じ変換処理が複数箇所に | DRY違反 | 共通関数に抽出 |
良い抽象化の例:
```tsx
// 条件分岐が肥大化
function UserBadge({ user }) {
if (user.role === 'admin') {
return <span className="bg-red-500">管理者</span>
} else if (user.role === 'moderator') {
return <span className="bg-yellow-500">モデレーター</span>
} else if (user.role === 'premium') {
return <span className="bg-purple-500">プレミアム</span>
} else {
return <span className="bg-gray-500">一般</span>
}
}
// Mapで抽象化
const ROLE_CONFIG = {
admin: { label: '管理者', className: 'bg-red-500' },
moderator: { label: 'モデレーター', className: 'bg-yellow-500' },
premium: { label: 'プレミアム', className: 'bg-purple-500' },
default: { label: '一般', className: 'bg-gray-500' },
}
function UserBadge({ user }) {
const config = ROLE_CONFIG[user.role] ?? ROLE_CONFIG.default
return <span className={config.className}>{config.label}</span>
}
```
```tsx
// 抽象度が混在
function OrderList() {
const [orders, setOrders] = useState([])
useEffect(() => {
fetch('/api/orders')
.then(res => res.json())
.then(data => setOrders(data))
}, [])
return orders.map(order => (
<div>{order.total.toLocaleString()}円</div>
))
}
// 抽象度を揃える
function OrderList() {
const { data: orders } = useOrders() // データ取得を隠蔽
return orders.map(order => (
<OrderItem key={order.id} order={order} />
))
}
```
## フロントエンドとバックエンドの責務分離
### 表示形式の責務
バックエンドは「データ」を返し、フロントエンドが「表示形式」に変換する。
```tsx
// フロントエンド: 表示形式に変換
export function formatPrice(amount: number): string {
return `¥${amount.toLocaleString()}`
}
export function formatDate(date: Date): string {
return format(date, 'yyyy年M月d日')
}
```
| 基準 | 判定 |
|------|------|
| バックエンドが表示用文字列を返している | 設計見直しを提案 |
| 同じフォーマット処理が複数箇所にコピペ | ユーティリティ関数に統一 |
| コンポーネント内でインラインフォーマット | 関数に抽出 |
### ドメインロジックの配置（SmartUI排除）
ドメインロジック（ビジネスルール）はバックエンドに配置。フロントエンドは状態の表示・編集のみ。
ドメインロジックとは:
- 集約のビジネスルール（在庫判定、価格計算、ステータス遷移）
- バリデーション（業務制約の検証）
- 不変条件の保証
フロントエンドの責務:
- サーバーから受け取った状態を表示
- ユーザー入力を収集し、コマンドとしてバックエンドに送信
- UI専用の一時状態管理（フォーカス、ホバー、モーダル開閉）
- 表示形式の変換（フォーマット、ソート、フィルタ）
| 基準 | 判定 |
|------|------|
| フロントエンドで価格計算・在庫判定 | バックエンドに移動 → REJECT |
| フロントエンドでステータス遷移ルール | バックエンドに移動 → REJECT |
| フロントエンドでビジネスバリデーション | バックエンドに移動 → REJECT |
| サーバー側で計算可能な値をフロントで再計算 | 冗長 → REJECT |
良い例 vs 悪い例:
```tsx
// BAD - フロントエンドでビジネスルール
function OrderForm({ order }: { order: Order }) {
const totalPrice = order.items.reduce((sum, item) =>
sum + item.price * item.quantity, 0
)
const canCheckout = totalPrice >= 1000 && order.items.every(i => i.stock > 0)
return <button disabled={!canCheckout}>注文確定</button>
}
// GOOD - バックエンドから受け取った状態を表示
function OrderForm({ order }: { order: Order }) {
// totalPrice, canCheckout はサーバーから受け取る
return (
<>
<div>{formatPrice(order.totalPrice)}</div>
<button disabled={!order.canCheckout}>注文確定</button>
</>
)
}
```
```tsx
// BAD - フロントエンドでステータス遷移判定
function TaskCard({ task }: { task: Task }) {
const canStart = task.status === 'pending' && task.assignee !== null
const canComplete = task.status === 'in_progress' && /* 複雑な条件... */
return (
<>
<button onClick={startTask} disabled={!canStart}>開始</button>
<button onClick={completeTask} disabled={!canComplete}>完了</button>
</>
)
}
// GOOD - サーバーが許可するアクションを返す
function TaskCard({ task }: { task: Task }) {
// task.allowedActions = ['start', 'cancel'] など、サーバーが計算
const canStart = task.allowedActions.includes('start')
const canComplete = task.allowedActions.includes('complete')
return (
<>
<button onClick={startTask} disabled={!canStart}>開始</button>
<button onClick={completeTask} disabled={!canComplete}>完了</button>
</>
)
}
```
例外（フロントエンドにロジックを置いてもOK）:
| ケース | 理由 |
|--------|------|
| UI専用バリデーション | 「必須入力」「文字数制限」等のUXフィードバック（サーバー側でも検証必須） |
| クライアント側フィルタ/ソート | サーバーから受け取ったリストの表示順序変更 |
| 表示条件の分岐 | 「ログイン済みなら詳細表示」等のUI制御 |
| リアルタイムフィードバック | 入力中のプレビュー表示 |
判断基準: 「この計算結果がサーバーとズレたら業務が壊れるか?」
- YES → バックエンドに配置（ドメインロジック）
- NO → フロントエンドでもOK（表示ロジック）
## パフォーマンス
| 基準 | 判定 |
|------|------|
| 不要な再レンダリング | 最適化が必要 |
| 大きなリストの仮想化なし | 警告 |
| 画像の最適化なし | 警告 |
| バンドルに未使用コード | tree-shakingを確認 |
| メモ化の過剰使用 | 本当に必要か確認 |
最適化チェックリスト:
- `React.memo` / `useMemo` / `useCallback` は適切か
- 大きなリストは仮想スクロール対応か
- Code Splittingは適切か
- 画像はlazy loadingされているか
アンチパターン:
```tsx
// レンダリングごとに新しいオブジェクト
<Child style={{ color: 'red' }} />
// 定数化 or useMemo
const style = useMemo(() => ({ color: 'red' }), []);
<Child style={style} />
```
## アクセシビリティ
| 基準 | 判定 |
|------|------|
| インタラクティブ要素にキーボード対応なし | REJECT |
| 画像にalt属性なし | REJECT |
| フォーム要素にlabelなし | REJECT |
| 色だけで情報を伝達 | REJECT |
| フォーカス管理の欠如（モーダル等） | REJECT |
チェックリスト:
- セマンティックHTMLを使用しているか
- ARIA属性は適切か（過剰でないか）
- キーボードナビゲーション可能か
- スクリーンリーダーで意味が通じるか
- カラーコントラストは十分か
## TypeScript/型安全性
| 基準 | 判定 |
|------|------|
| `any` 型の使用 | REJECT |
| 型アサーション（as）の乱用 | 要検討 |
| Props型定義なし | REJECT |
| イベントハンドラの型が不適切 | 修正が必要 |
## フロントエンドセキュリティ
| 基準 | 判定 |
|------|------|
| dangerouslySetInnerHTML使用 | XSSリスクを確認 |
| ユーザー入力の未サニタイズ | REJECT |
| 機密情報のフロントエンド保存 | REJECT |
| CSRFトークンの未使用 | 要確認 |
## テスタビリティ
| 基準 | 判定 |
|------|------|
| data-testid等の未付与 | 警告 |
| テスト困難な構造 | 分離を検討 |
| ビジネスロジックのUIへの埋め込み | REJECT |
## アンチパターン検出
以下を見つけたら REJECT:
| アンチパターン | 問題 |
|---------------|------|
| God Component | 1コンポーネントに全機能が集中 |
| Prop Drilling | 深いPropsバケツリレー |
| Inline Styles乱用 | 保守性低下 |
| useEffect地獄 | 依存関係が複雑すぎる |
| Premature Optimization | 不要なメモ化 |
| Magic Strings | ハードコードされた文字列 |
| Hidden Dependencies | 子コンポーネントの隠れたAPI呼び出し |
| Over-generalization | 無理やり汎用化したコンポーネント |

164
resources/global/ja/knowledge/security.md Normal file
View File

@ -0,0 +1,164 @@
# セキュリティ知識
## AI生成コードのセキュリティ問題
AI生成コードには特有の脆弱性パターンがある。
| パターン | リスク | 例 |
|---------|--------|-----|
| もっともらしいが危険なデフォルト | 高 | `cors: { origin: '*' }` は問題なく見えるが危険 |
| 古いセキュリティプラクティス | 中 | 非推奨の暗号化、古い認証パターンの使用 |
| 不完全なバリデーション | 高 | 形式は検証するがビジネスルールを検証しない |
| 入力を過度に信頼 | 重大 | 内部APIは常に安全と仮定 |
| コピペによる脆弱性 | 高 | 同じ危険なパターンが複数ファイルで繰り返される |
特に厳しく審査が必要:
- 認証・認可ロジック（AIはエッジケースを見落としがち）
- 入力バリデーション（AIは構文を検証しても意味を見落とす可能性）
- エラーメッセージ（AIは内部詳細を露出する可能性）
- 設定ファイル（AIは学習データから危険なデフォルトを使う可能性）
## インジェクション攻撃
**SQLインジェクション**
- 文字列連結によるSQL構築 → REJECT
- パラメータ化クエリの不使用 → REJECT
- ORMの raw query での未サニタイズ入力 → REJECT
```typescript
// NG
db.query(`SELECT * FROM users WHERE id = ${userId}`)
// OK
db.query('SELECT * FROM users WHERE id = ?', [userId])
```
**コマンドインジェクション**
- `exec()`, `spawn()` での未検証入力 → REJECT
- シェルコマンド構築時のエスケープ不足 → REJECT
```typescript
// NG
exec(`ls ${userInput}`)
// OK
execFile('ls', [sanitizedInput])
```
**XSS (Cross-Site Scripting)**
- HTML/JSへの未エスケープ出力 → REJECT
- `innerHTML`, `dangerouslySetInnerHTML` の不適切な使用 → REJECT
- URLパラメータの直接埋め込み → REJECT
## 認証・認可
**認証の問題**
- ハードコードされたクレデンシャル → 即REJECT
- 平文パスワードの保存 → 即REJECT
- 弱いハッシュアルゴリズム (MD5, SHA1) → REJECT
- セッショントークンの不適切な管理 → REJECT
**認可の問題**
- 権限チェックの欠如 → REJECT
- IDOR (Insecure Direct Object Reference) → REJECT
- 権限昇格の可能性 → REJECT
```typescript
// NG - 権限チェックなし
app.get('/user/:id', (req, res) => {
return db.getUser(req.params.id)
})
// OK
app.get('/user/:id', authorize('read:user'), (req, res) => {
if (req.user.id !== req.params.id && !req.user.isAdmin) {
return res.status(403).send('Forbidden')
}
return db.getUser(req.params.id)
})
```
## データ保護
**機密情報の露出**
- APIキー、シークレットのハードコーディング → 即REJECT
- ログへの機密情報出力 → REJECT
- エラーメッセージでの内部情報露出 → REJECT
- `.env` ファイルのコミット → REJECT
**データ検証**
- 入力値の未検証 → REJECT
- 型チェックの欠如 → REJECT
- サイズ制限の未設定 → REJECT
## 暗号化
- 弱い暗号アルゴリズムの使用 → REJECT
- 固定IV/Nonceの使用 → REJECT
- 暗号化キーのハードコーディング → 即REJECT
- HTTPSの未使用（本番環境） → REJECT
## ファイル操作
**パストラバーサル**
- ユーザー入力を含むファイルパス → REJECT
- `../` のサニタイズ不足 → REJECT
```typescript
// NG
const filePath = path.join(baseDir, userInput)
fs.readFile(filePath)
// OK
const safePath = path.resolve(baseDir, userInput)
if (!safePath.startsWith(path.resolve(baseDir))) {
throw new Error('Invalid path')
}
```
**ファイルアップロード**
- ファイルタイプの未検証 → REJECT
- ファイルサイズ制限なし → REJECT
- 実行可能ファイルのアップロード許可 → REJECT
## 依存関係
- 既知の脆弱性を持つパッケージ → REJECT
- メンテナンスされていないパッケージ → 警告
- 不必要な依存関係 → 警告
## エラーハンドリング
- スタックトレースの本番露出 → REJECT
- 詳細なエラーメッセージの露出 → REJECT
- エラーの握りつぶし（セキュリティイベント） → REJECT
## レート制限・DoS対策
- レート制限の欠如（認証エンドポイント） → 警告
- リソース枯渇攻撃の可能性 → 警告
- 無限ループの可能性 → REJECT
## OWASP Top 10 チェックリスト
| カテゴリ | 確認事項 |
|---------|---------|
| A01 Broken Access Control | 認可チェック、CORS設定 |
| A02 Cryptographic Failures | 暗号化、機密データ保護 |
| A03 Injection | SQL, コマンド, XSS |
| A04 Insecure Design | セキュリティ設計パターン |
| A05 Security Misconfiguration | デフォルト設定、不要な機能 |
| A06 Vulnerable Components | 依存関係の脆弱性 |
| A07 Auth Failures | 認証メカニズム |
| A08 Software Integrity | コード署名、CI/CD |
| A09 Logging Failures | セキュリティログ |
| A10 SSRF | サーバーサイドリクエスト |

428
resources/global/ja/personas/architecture-reviewer.md
View File

@ -24,431 +24,3 @@
- 軽微な問題でも後に持ち越さない。今修正できる問題は今修正させる - 軽微な問題でも後に持ち越さない。今修正できる問題は今修正させる
- 「条件付き承認」はしない。問題があれば差し戻す - 「条件付き承認」はしない。問題があれば差し戻す
- 既存コードの踏襲を理由にした問題の放置は認めない - 既存コードの踏襲を理由にした問題の放置は認めない
## ドメイン知識
### 構造・設計
**ファイル分割**
| 基準 | 判定 |
|--------------|------|
| 1ファイル200行超 | 分割を検討 |
| 1ファイル300行超 | REJECT |
| 1ファイルに複数の責務 | REJECT |
| 関連性の低いコードが同居 | REJECT |
**モジュール構成**
- 高凝集: 関連する機能がまとまっているか
- 低結合: モジュール間の依存が最小限か
- 循環依存がないか
- 適切なディレクトリ階層か
**関数設計**
- 1関数1責務になっているか
- 30行を超える関数は分割を検討
- 副作用が明確か
**レイヤー設計**
- 依存の方向: 上位層 → 下位層（逆方向禁止）
- Controller → Service → Repository の流れが守られているか
- 1インターフェース = 1責務（巨大なServiceクラス禁止）
**ディレクトリ構造**
構造パターンの選択:
| パターン | 適用場面 | 例 |
|---------|---------|-----|
| レイヤード | 小規模、CRUD中心 | `controllers/`, `services/`, `repositories/` |
| Vertical Slice | 中〜大規模、機能独立性が高い | `features/auth/`, `features/order/` |
| ハイブリッド | 共通基盤 + 機能モジュール | `core/` + `features/` |
Vertical Slice Architecture（機能単位でコードをまとめる構造）:
```
src/
├── features/
│ ├── auth/
│ │ ├── LoginCommand.ts
│ │ ├── LoginHandler.ts
│ │ ├── AuthRepository.ts
│ │ └── auth.test.ts
│ └── order/
│ ├── CreateOrderCommand.ts
│ ├── CreateOrderHandler.ts
│ └── ...
└── shared/ # 複数featureで共有
├── database/
└── middleware/
```
Vertical Slice の判定基準:
| 基準 | 判定 |
|------|------|
| 1機能が3ファイル以上のレイヤーに跨る | Slice化を検討 |
| 機能間の依存がほぼない | Slice化推奨 |
| 共通処理が50%以上 | レイヤード維持 |
| チームが機能別に分かれている | Slice化必須 |
禁止パターン:
| パターン | 問題 |
|---------|------|
| `utils/` の肥大化 | 責務不明の墓場になる |
| `common/` への安易な配置 | 依存関係が不明確になる |
| 深すぎるネスト（4階層超） | ナビゲーション困難 |
| 機能とレイヤーの混在 | `features/services/` は禁止 |
**責務の分離**
- 読み取りと書き込みの責務が分かれているか
- データ取得はルート（View/Controller）で行い、子に渡しているか
- エラーハンドリングが一元化されているか（各所でtry-catch禁止）
- ビジネスロジックがController/Viewに漏れていないか
### コード品質の検出手法
**説明コメント（What/How）の検出基準**
コードの動作をそのまま言い換えているコメントを検出する。
| 判定 | 基準 |
|------|------|
| REJECT | コードの動作をそのまま自然言語で言い換えている |
| REJECT | 関数名・変数名から明らかなことを繰り返している |
| REJECT | JSDocが関数名の言い換えだけで情報を追加していない |
| OK | なぜその実装を選んだかの設計判断を説明している |
| OK | 一見不自然に見える挙動の理由を説明している |
| 最良 | コメントなしでコード自体が意図を語っている |
```typescript
// REJECT - コードの言い換え（What）
// If interrupted, abort immediately
if (status === 'interrupted') {
return ABORT_STEP;
}
// REJECT - ループの存在を言い換えただけ
// Check transitions in order
for (const transition of step.transitions) {
// REJECT - 関数名の繰り返し
/** Check if status matches transition condition. */
export function matchesCondition(status: Status, condition: TransitionCondition): boolean {
// OK - 設計判断の理由（Why）
// ユーザー中断はピース定義のトランジションより優先する
if (status === 'interrupted') {
return ABORT_STEP;
}
// OK - 一見不自然な挙動の理由
// stay はループを引き起こす可能性があるが、ユーザーが明示的に指定した場合のみ使われる
return step.name;
```
**状態の直接変更の検出基準**
配列やオブジェクトの直接変更（ミューテーション）を検出する。
```typescript
// REJECT - 配列の直接変更
const steps: Step[] = getSteps();
steps.push(newStep); // 元の配列を破壊
steps.splice(index, 1); // 元の配列を破壊
steps[0].status = 'done'; // ネストされたオブジェクトも直接変更
// OK - イミュータブルな操作
const withNew = [...steps, newStep];
const without = steps.filter((_, i) => i !== index);
const updated = steps.map((s, i) =>
i === 0 ? { ...s, status: 'done' } : s
);
// REJECT - オブジェクトの直接変更
function updateConfig(config: Config) {
config.logLevel = 'debug'; // 引数を直接変更
config.steps.push(newStep); // ネストも直接変更
return config;
}
// OK - 新しいオブジェクトを返す
function updateConfig(config: Config): Config {
return {
...config,
logLevel: 'debug',
steps: [...config.steps, newStep],
};
}
```
### セキュリティ（基本チェック）
- インジェクション対策（SQL, コマンド, XSS）
- ユーザー入力の検証
- 機密情報のハードコーディング
### テスタビリティ
- 依存性注入が可能な設計か
- モック可能か
- テストが書かれているか
### アンチパターン検出
以下のパターンを見つけたら REJECT:
| アンチパターン | 問題 |
|---------------|------|
| God Class/Component | 1つのクラスが多くの責務を持っている |
| Feature Envy | 他モジュールのデータを頻繁に参照している |
| Shotgun Surgery | 1つの変更が複数ファイルに波及する構造 |
| 過度な汎用化 | 今使わないバリアントや拡張ポイント |
| 隠れた依存 | 子コンポーネントが暗黙的にAPIを呼ぶ等 |
| 非イディオマティック | 言語・FWの作法を無視した独自実装 |
### 抽象化レベルの評価
**条件分岐の肥大化検出**
| パターン | 判定 |
|---------|------|
| 同じif-elseパターンが3箇所以上 | ポリモーフィズムで抽象化 → REJECT |
| switch/caseが5分岐以上 | Strategy/Mapパターンを検討 |
| フラグ引数で挙動を変える | 別関数に分割 → REJECT |
| 型による分岐（instanceof/typeof） | ポリモーフィズムに置換 → REJECT |
| ネストした条件分岐（3段以上） | 早期リターンまたは抽出 → REJECT |
**抽象度の不一致検出**
| パターン | 問題 | 修正案 |
|---------|------|--------|
| 高レベル処理の中に低レベル詳細 | 読みにくい | 詳細を関数に抽出 |
| 1関数内で抽象度が混在 | 認知負荷 | 同じ粒度に揃える |
| ビジネスロジックにDB操作が混在 | 責務違反 | Repository層に分離 |
| 設定値と処理ロジックが混在 | 変更困難 | 設定を外部化 |
**良い抽象化の例**
```typescript
// 条件分岐の肥大化
function process(type: string) {
if (type === 'A') { /* 処理A */ }
else if (type === 'B') { /* 処理B */ }
else if (type === 'C') { /* 処理C */ }
// ...続く
}
// Mapパターンで抽象化
const processors: Record<string, () => void> = {
A: processA,
B: processB,
C: processC,
};
function process(type: string) {
processors[type]?.();
}
```
```typescript
// 抽象度の混在
function createUser(data: UserData) {
// 高レベル: ビジネスロジック
validateUser(data);
// 低レベル: DB操作の詳細
const conn = await pool.getConnection();
await conn.query('INSERT INTO users...');
conn.release();
}
// 抽象度を揃える
function createUser(data: UserData) {
validateUser(data);
await userRepository.save(data); // 詳細は隠蔽
}
```
### その場しのぎの検出
「とりあえず動かす」ための妥協を見逃さない。
| パターン | 例 |
|---------|-----|
| 不要なパッケージ追加 | 動かすためだけに入れた謎のライブラリ |
| テストの削除・スキップ | `@Disabled`、`.skip()`、コメントアウト |
| 空実装・スタブ放置 | `return null`、`// TODO: implement`、`pass` |
| モックデータの本番混入 | ハードコードされたダミーデータ |
| エラー握りつぶし | 空の `catch {}`、`rescue nil` |
| マジックナンバー | 説明なしの `if (status == 3)` |
### TODOコメントの厳格な禁止
「将来やる」は決してやらない。今やらないことは永遠にやらない。
TODOコメントは即REJECT。
```kotlin
// REJECT - 将来を見越したTODO
// TODO: 施設IDによる認可チェックを追加
fun deleteCustomHoliday(@PathVariable id: String) {
deleteCustomHolidayInputPort.execute(input)
}
// APPROVE - 今実装する
fun deleteCustomHoliday(@PathVariable id: String) {
val currentUserFacilityId = getCurrentUserFacilityId()
val holiday = findHolidayById(id)
require(holiday.facilityId == currentUserFacilityId) {
"Cannot delete holiday from another facility"
}
deleteCustomHolidayInputPort.execute(input)
}
```
TODOが許容される唯一のケース:
| 条件 | 例 | 判定 |
|------|-----|------|
| 外部依存で今は実装不可 + Issue化済み | `// TODO(#123): APIキー取得後に実装` | 許容 |
| 技術的制約で回避不可 + Issue化済み | `// TODO(#456): ライブラリバグ修正待ち` | 許容 |
| 「将来実装」「後で追加」 | `// TODO: バリデーション追加` | REJECT |
| 「時間がないので」 | `// TODO: リファクタリング` | REJECT |
正しい対処:
- 今必要 → 今実装する
- 今不要 → コードを削除する
- 外部要因で不可 → Issue化してチケット番号をコメントに入れる
### DRY違反の検出
重複コードを検出する。
| パターン | 判定 |
|---------|------|
| 同じロジックが3箇所以上 | 即REJECT - 関数/メソッドに抽出 |
| 同じバリデーションが2箇所以上 | 即REJECT - バリデーター関数に抽出 |
| 似たようなコンポーネントが3個以上 | 即REJECT - 共通コンポーネント化 |
| コピペで派生したコード | 即REJECT - パラメータ化または抽象化 |
AHA原則（Avoid Hasty Abstractions）とのバランス:
- 2回の重複 → 様子見
- 3回の重複 → 即抽出
- ドメインが異なる重複 → 抽象化しない（例: 顧客用バリデーションと管理者用バリデーションは別物）
### 仕様準拠の検証
変更が、プロジェクトの文書化された仕様に準拠しているか検証する。
検証対象:
| 対象 | 確認内容 |
|------|---------|
| CLAUDE.md / README.md | スキーマ定義、設計原則、制約に従っているか |
| 型定義・Zodスキーマ | 新しいフィールドがスキーマに反映されているか |
| YAML/JSON設定ファイル | 文書化されたフォーマットに従っているか |
具体的なチェック:
1. 設定ファイル（YAML等）を変更・追加した場合:
- CLAUDE.md等に記載されたスキーマ定義と突合する
- 無視されるフィールドや無効なフィールドが含まれていないか
- 必須フィールドが欠落していないか
2. 型定義やインターフェースを変更した場合:
- ドキュメントのスキーマ説明が更新されているか
- 既存の設定ファイルが新しいスキーマと整合するか
このパターンを見つけたら REJECT:
| パターン | 問題 |
|---------|------|
| 仕様に存在しないフィールドの使用 | 無視されるか予期しない動作 |
| 仕様上無効な値の設定 | 実行時エラーまたは無視される |
| 文書化された制約への違反 | 設計意図に反する |
### 呼び出しチェーン検証
新しいパラメータ・フィールドが追加された場合、変更ファイル内だけでなく呼び出し元も検証する。
検証手順:
1. 新しいオプショナルパラメータや interface フィールドを見つけたら、`Grep` で全呼び出し元を検索
2. 全呼び出し元が新しいパラメータを渡しているか確認
3. フォールバック値（`?? default`）がある場合、フォールバックが使われるケースが意図通りか確認
危険パターン:
| パターン | 問題 | 検出方法 |
|---------|------|---------|
| `options.xxx ?? fallback` で全呼び出し元が `xxx` を省略 | 機能が実装されているのに常にフォールバック | grep で呼び出し元を確認 |
| テストがモックで直接値をセット | 実際の呼び出しチェーンを経由しない | テストの構築方法を確認 |
| `executeXxx()` が内部で使う `options` を引数で受け取らない | 上位から値を渡す口がない | 関数シグネチャを確認 |
```typescript
// 配線漏れ: projectCwd を受け取る口がない
export async function executePiece(config, cwd, task) {
const engine = new PieceEngine(config, cwd, task); // options なし
}
// 配線済み: projectCwd を渡せる
export async function executePiece(config, cwd, task, options?) {
const engine = new PieceEngine(config, cwd, task, options);
}
```
呼び出し元の制約による論理的デッドコード:
呼び出しチェーンの検証は「配線漏れ」だけでなく、逆方向——呼び出し元が既に保証している条件に対する不要な防御コード——にも適用する。
| パターン | 問題 | 検出方法 |
|---------|------|---------|
| 呼び出し元がTTY必須なのに関数内でTTYチェック | 到達しない分岐が残る | grep で全呼び出し元の前提条件を確認 |
| 呼び出し元がnullチェック済みなのに再度nullガード | 冗長な防御 | 呼び出し元の制約を追跡 |
| 呼び出し元が型で制約しているのにランタイムチェック | 型安全を信頼していない | TypeScriptの型制約を確認 |
検証手順:
1. 防御的な条件分岐（TTYチェック、nullガード等）を見つけたら、grep で全呼び出し元を確認
2. 全呼び出し元がその条件を既に保証しているなら、防御は不要 → REJECT
3. 一部の呼び出し元が保証していない場合は、防御を残す
### 品質特性
| 特性 | 確認観点 |
|------|---------|
| Scalability | 負荷増加に対応できる設計か |
| Maintainability | 変更・修正が容易か |
| Observability | ログ・監視が可能な設計か |
### 大局観
細かい「クリーンコード」の指摘に終始しない。
確認すべきこと:
- このコードは将来どう変化するか
- スケーリングの必要性は考慮されているか
- 技術的負債を生んでいないか
- ビジネス要件と整合しているか
- 命名がドメインと一貫しているか
### 変更スコープの評価
変更スコープを確認し、レポートに記載する（ブロッキングではない）。
| スコープサイズ | 変更行数 | 対応 |
|---------------|---------|------|
| Small | 〜200行 | そのままレビュー |
| Medium | 200-500行 | そのままレビュー |
| Large | 500行以上 | レビューは継続。分割可能か提案を付記 |
大きな変更が必要なタスクもある。行数だけでREJECTしない。
確認すること:
- 変更が論理的にまとまっているか（無関係な変更が混在していないか）
- Coderのスコープ宣言と実際の変更が一致しているか
提案として記載すること（ブロッキングではない）:
- 分割可能な場合は分割案を提示

418
resources/global/ja/personas/cqrs-es-reviewer.md
View File

@ -26,421 +26,3 @@
- 読み取りと書き込みは本質的に異なる関心事であり、無理に統合しない - 読み取りと書き込みは本質的に異なる関心事であり、無理に統合しない
- 形だけのCQRSを見逃さない。CRUDをCommand/Queryに分けただけでは意味がない - 形だけのCQRSを見逃さない。CRUDをCommand/Queryに分けただけでは意味がない
- シンプルなCRUDで十分なケースにCQRS+ESを強制しない - シンプルなCRUDで十分なケースにCQRS+ESを強制しない
## ドメイン知識
### Aggregate設計
Aggregateは判断に必要なフィールドのみ保持する。
Command Model（Aggregate）の役割は「コマンドを受けて判断し、イベントを発行する」こと。クエリ用データはRead Model（Projection）が担当する。
「判断に必要」とは:
- `if`/`require`の条件分岐に使う
- インスタンスメソッドでイベント発行時にフィールド値を参照する
| 基準 | 判定 |
|------|------|
| Aggregateが複数のトランザクション境界を跨ぐ | REJECT |
| Aggregate間の直接参照（ID参照でない） | REJECT |
| Aggregateが100行を超える | 分割を検討 |
| ビジネス不変条件がAggregate外にある | REJECT |
| 判断に使わないフィールドを保持 | REJECT |
良いAggregate:
```kotlin
// 判断に必要なフィールドのみ
data class Order(
val orderId: String, // イベント発行時に使用
val status: OrderStatus // 状態チェックに使用
) {
fun confirm(confirmedBy: String): OrderConfirmedEvent {
require(status == OrderStatus.PENDING) { "確定できる状態ではありません" }
return OrderConfirmedEvent(
orderId = orderId,
confirmedBy = confirmedBy,
confirmedAt = LocalDateTime.now()
)
}
}
// 判断に使わないフィールドを保持（NG）
data class Order(
val orderId: String,
val customerId: String, // 判断に未使用
val shippingAddress: Address, // 判断に未使用
val status: OrderStatus
)
```
追加操作がないAggregateはIDのみ:
```kotlin
// 作成のみで追加操作がない場合
data class Notification(val notificationId: String) {
companion object {
fun create(customerId: String, message: String): NotificationCreatedEvent {
return NotificationCreatedEvent(
notificationId = UUID.randomUUID().toString(),
customerId = customerId,
message = message
)
}
}
}
```
### イベント設計
| 基準 | 判定 |
|------|------|
| イベントが過去形でない（Created → Create） | REJECT |
| イベントにロジックが含まれる | REJECT |
| イベントが他Aggregateの内部状態を含む | REJECT |
| イベントのスキーマがバージョン管理されていない | 警告 |
| CRUDスタイルのイベント（Updated, Deleted） | 要検討 |
良いイベント:
```kotlin
// Good: ドメインの意図が明確
OrderPlaced, PaymentReceived, ItemShipped
// Bad: CRUDスタイル
OrderUpdated, OrderDeleted
```
イベント粒度:
- 細かすぎ: `OrderFieldChanged` → ドメインの意図が不明
- 適切: `ShippingAddressChanged` → 意図が明確
- 粗すぎ: `OrderModified` → 何が変わったか不明
### コマンドハンドラ
| 基準 | 判定 |
|------|------|
| ハンドラがDBを直接操作 | REJECT |
| ハンドラが複数Aggregateを変更 | REJECT |
| コマンドのバリデーションがない | REJECT |
| ハンドラがクエリを実行して判断 | 要検討 |
良いコマンドハンドラ:
```
1. コマンドを受け取る
2. Aggregateをイベントストアから復元
3. Aggregateにコマンドを適用
4. 発行されたイベントを保存
```
### プロジェクション設計
| 基準 | 判定 |
|------|------|
| プロジェクションがコマンドを発行 | REJECT |
| プロジェクションがWriteモデルを参照 | REJECT |
| 複数のユースケースを1つのプロジェクションで賄う | 要検討 |
| リビルド不可能な設計 | REJECT |
良いプロジェクション:
- 特定の読み取りユースケースに最適化
- イベントから冪等に再構築可能
- Writeモデルから完全に独立
### Query側の設計
ControllerはQueryGatewayを使う。Repositoryを直接使わない。
レイヤー間の型:
- `application/query/` - Query結果の型（例: `OrderDetail`）
- `adapter/protocol/` - RESTレスポンスの型（例: `OrderDetailResponse`）
- QueryHandlerはapplication層の型を返し、Controllerがadapter層の型に変換
```kotlin
// application/query/OrderDetail.kt
data class OrderDetail(
val orderId: String,
val customerName: String,
val totalAmount: Money
)
// adapter/protocol/OrderDetailResponse.kt
data class OrderDetailResponse(...) {
companion object {
fun from(detail: OrderDetail) = OrderDetailResponse(...)
}
}
// QueryHandler - application層の型を返す
@QueryHandler
fun handle(query: GetOrderDetailQuery): OrderDetail? {
val entity = repository.findById(query.id) ?: return null
return OrderDetail(...)
}
// Controller - adapter層の型に変換
@GetMapping("/{id}")
fun getById(@PathVariable id: String): ResponseEntity<OrderDetailResponse> {
val detail = queryGateway.query(
GetOrderDetailQuery(id),
OrderDetail::class.java
).join() ?: throw NotFoundException("...")
return ResponseEntity.ok(OrderDetailResponse.from(detail))
}
```
構成:
```
Controller (adapter) → QueryGateway → QueryHandler (application) → Repository
↓ ↓
Response.from(detail) OrderDetail
```
### 結果整合性
| 状況 | 対応 |
|------|------|
| UIが即座に更新を期待している | 設計見直し or ポーリング/WebSocket |
| 整合性遅延が許容範囲を超える | アーキテクチャ再検討 |
| 補償トランザクションが未定義 | 障害シナリオの検討を要求 |
### Saga vs EventHandler
Sagaは「競合が発生する複数アグリゲート間の操作」にのみ使用する。
Sagaが必要なケース:
```
複数のアクターが同じリソースを取り合う場合
例: 在庫確保（10人が同時に同じ商品を注文）
OrderPlacedEvent
↓ InventoryReservationSaga
ReserveInventoryCommand → Inventory集約（同時実行を直列化）
↓
InventoryReservedEvent → ConfirmOrderCommand
InventoryReservationFailedEvent → CancelOrderCommand
```
Sagaが不要なケース:
```
競合が発生しない操作
例: 注文キャンセル時の在庫解放
OrderCancelledEvent
↓ InventoryReleaseHandler（単純なEventHandler）
ReleaseInventoryCommand
↓
InventoryReleasedEvent
```
判断基準:
| 状況 | Saga | EventHandler |
|------|------|--------------|
| リソースの取り合いがある | 使う | - |
| 補償トランザクションが必要 | 使う | - |
| 競合しない単純な連携 | - | 使う |
| 失敗時は再試行で十分 | - | 使う |
アンチパターン:
```kotlin
// NG - ライフサイクル管理のためにSagaを使う
@Saga
class OrderLifecycleSaga {
// 注文の全状態遷移をSagaで追跡
// PLACED → CONFIRMED → SHIPPED → DELIVERED
}
// OK - 結果整合性が必要な操作だけをSagaで処理
@Saga
class InventoryReservationSaga {
// 在庫確保の同時実行制御のみ
}
```
Sagaはライフサイクル管理ツールではない。結果整合性が必要な「操作」単位で作成する。
### 例外 vs イベント（失敗時の選択）
監査不要な失敗は例外、監査が必要な失敗はイベント。
例外アプローチ（推奨: ほとんどのケース）:
```kotlin
// ドメインモデル: バリデーション失敗時に例外をスロー
fun reserveInventory(orderId: String, quantity: Int): InventoryReservedEvent {
if (availableQuantity < quantity) {
throw InsufficientInventoryException("在庫が不足しています")
}
return InventoryReservedEvent(productId, orderId, quantity)
}
// Saga: exceptionally でキャッチして補償アクション
commandGateway.send<Any>(command)
.exceptionally { ex ->
commandGateway.send<Any>(CancelOrderCommand(
orderId = orderId,
reason = ex.cause?.message ?: "在庫確保に失敗しました"
))
null
}
```
イベントアプローチ（稀なケース）:
```kotlin
// 監査が必要な場合のみ
data class PaymentFailedEvent(
val paymentId: String,
val reason: String,
val attemptedAmount: Money
) : PaymentEvent
```
判断基準:
| 質問 | 例外 | イベント |
|------|------|----------|
| この失敗を後で確認する必要があるか? | No | Yes |
| 規制やコンプライアンスで記録が必要か? | No | Yes |
| Sagaだけが失敗を気にするか? | Yes | No |
| Event Storeに残すと価値があるか? | No | Yes |
デフォルトは例外アプローチ。監査要件がある場合のみイベントを検討する。
### 抽象化レベルの評価
**条件分岐の肥大化検出**
| パターン | 判定 |
|---------|------|
| 同じif-elseパターンが3箇所以上 | ポリモーフィズムで抽象化 → REJECT |
| switch/caseが5分岐以上 | Strategy/Mapパターンを検討 |
| イベント種別による分岐が増殖 | イベントハンドラを分離 → REJECT |
| Aggregate内の状態分岐が複雑 | State Patternを検討 |
**抽象度の不一致検出**
| パターン | 問題 | 修正案 |
|---------|------|--------|
| CommandHandlerにDB操作詳細 | 責務違反 | Repository層に分離 |
| EventHandlerにビジネスロジック | 責務違反 | ドメインサービスに抽出 |
| Aggregateに永続化処理 | レイヤー違反 | EventStore経由に変更 |
| Projectionに計算ロジック | 保守困難 | 専用サービスに抽出 |
良い抽象化の例:
```kotlin
// イベント種別による分岐の増殖（NG）
@EventHandler
fun on(event: DomainEvent) {
when (event) {
is OrderPlacedEvent -> handleOrderPlaced(event)
is OrderConfirmedEvent -> handleOrderConfirmed(event)
is OrderShippedEvent -> handleOrderShipped(event)
// ...どんどん増える
}
}
// イベントごとにハンドラを分離（OK）
@EventHandler
fun on(event: OrderPlacedEvent) { ... }
@EventHandler
fun on(event: OrderConfirmedEvent) { ... }
@EventHandler
fun on(event: OrderShippedEvent) { ... }
```
```kotlin
// 状態による分岐が複雑（NG）
fun process(command: ProcessCommand) {
when (status) {
PENDING -> if (command.type == "approve") { ... } else if (command.type == "reject") { ... }
APPROVED -> if (command.type == "ship") { ... }
// ...複雑化
}
}
// State Patternで抽象化（OK）
sealed class OrderState {
abstract fun handle(command: ProcessCommand): List<DomainEvent>
}
class PendingState : OrderState() {
override fun handle(command: ProcessCommand) = when (command) {
is ApproveCommand -> listOf(OrderApprovedEvent(...))
is RejectCommand -> listOf(OrderRejectedEvent(...))
else -> throw InvalidCommandException()
}
}
```
### アンチパターン検出
以下を見つけたら REJECT:
| アンチパターン | 問題 |
|---------------|------|
| CRUD偽装 | CQRSの形だけ真似てCRUD実装 |
| Anemic Domain Model | Aggregateが単なるデータ構造 |
| Event Soup | 意味のないイベントが乱発される |
| Temporal Coupling | イベント順序に暗黙の依存 |
| Missing Events | 重要なドメインイベントが欠落 |
| God Aggregate | 1つのAggregateに全責務が集中 |
### テスト戦略
レイヤーごとにテスト方針を分ける。
テストピラミッド:
```
┌─────────────┐
│ E2E Test │ ← 少数: 全体フロー確認
├─────────────┤
│ Integration │ ← Command→Event→Projection→Query の連携確認
├─────────────┤
│ Unit Test │ ← 多数: 各レイヤー独立テスト
└─────────────┘
```
Command側（Aggregate）:
```kotlin
// AggregateTestFixture使用
@Test
fun `確定コマンドでイベントが発行される`() {
fixture
.given(OrderPlacedEvent(...))
.`when`(ConfirmOrderCommand(orderId, confirmedBy))
.expectSuccessfulHandlerExecution()
.expectEvents(OrderConfirmedEvent(...))
}
```
Query側:
```kotlin
// Read Model直接セットアップ + QueryGateway
@Test
fun `注文詳細が取得できる`() {
// Given: Read Modelを直接セットアップ
orderRepository.save(OrderEntity(...))
// When: QueryGateway経由でクエリ実行
val detail = queryGateway.query(GetOrderDetailQuery(orderId), ...).join()
// Then
assertEquals(expectedDetail, detail)
}
```
チェック項目:
| 観点 | 判定 |
|------|------|
| Aggregateテストが状態ではなくイベントを検証している | 必須 |
| Query側テストがCommand経由でデータを作っていない | 推奨 |
| 統合テストでAxonの非同期処理を考慮している | 必須 |
### インフラ層
確認事項:
- イベントストアの選択は適切か
- メッセージング基盤は要件を満たすか
- スナップショット戦略は定義されているか
- イベントのシリアライズ形式は適切か

498
resources/global/ja/personas/frontend-reviewer.md
View File

@ -27,501 +27,3 @@
- アクセシビリティは後付け困難。最初から組み込む - アクセシビリティは後付け困難。最初から組み込む
- 過度な抽象化を警戒。シンプルに保つ - 過度な抽象化を警戒。シンプルに保つ
- フレームワークの作法に従う。独自パターンより標準的なアプローチ - フレームワークの作法に従う。独自パターンより標準的なアプローチ
## ドメイン知識
### コンポーネント設計
1ファイルにベタ書きしない。必ずコンポーネント分割する。
分離が必須なケース:
- 独自のstateを持つ → 必ず分離
- 50行超のJSX → 分離
- 再利用可能 → 分離
- 責務が複数 → 分離
- ページ内の独立したセクション → 分離
| 基準 | 判定 |
|------|------|
| 1コンポーネント200行超 | 分割を検討 |
| 1コンポーネント300行超 | REJECT |
| 表示とロジックが混在 | 分離を検討 |
| Props drilling（3階層以上） | 状態管理の導入を検討 |
| 複数の責務を持つコンポーネント | REJECT |
良いコンポーネント:
- 単一責務: 1つのことをうまくやる
- 自己完結: 必要な依存が明確
- テスト可能: 副作用が分離されている
コンポーネント分類:
| 種類 | 責務 | 例 |
|------|------|-----|
| Container | データ取得・状態管理 | `UserListContainer` |
| Presentational | 表示のみ | `UserCard` |
| Layout | 配置・構造 | `PageLayout`, `Grid` |
| Utility | 共通機能 | `ErrorBoundary`, `Portal` |
ディレクトリ構成:
```
features/{feature-name}/
├── components/
│ ├── {feature}-view.tsx # メインビュー（子を組み合わせる）
│ ├── {sub-component}.tsx # サブコンポーネント
│ └── index.ts
├── hooks/
├── types.ts
└── index.ts
```
### 状態管理
子コンポーネントは自身で状態を変更しない。イベントを親にバブリングし、親が状態を操作する。
```tsx
// 子が自分で状態を変更（NG）
const ChildBad = ({ initialValue }: { initialValue: string }) => {
const [value, setValue] = useState(initialValue)
return <input value={value} onChange={e => setValue(e.target.value)} />
}
// 親が状態を管理、子はコールバックで通知（OK）
const ChildGood = ({ value, onChange }: { value: string; onChange: (v: string) => void }) => {
return <input value={value} onChange={e => onChange(e.target.value)} />
}
const Parent = () => {
const [value, setValue] = useState('')
return <ChildGood value={value} onChange={setValue} />
}
```
例外（子がローカルstate持ってOK）:
- UI専用の一時状態（ホバー、フォーカス、アニメーション）
- 親に伝える必要がない完全にローカルな状態
| 基準 | 判定 |
|------|------|
| 不要なグローバル状態 | ローカル化を検討 |
| 同じ状態が複数箇所で管理 | 正規化が必要 |
| 子から親への状態変更（逆方向データフロー） | REJECT |
| APIレスポンスをそのまま状態に | 正規化を検討 |
| useEffectの依存配列が不適切 | REJECT |
状態配置の判断基準:
| 状態の性質 | 推奨配置 |
|-----------|---------|
| UIの一時的な状態（モーダル開閉等） | ローカル（useState） |
| フォームの入力値 | ローカル or フォームライブラリ |
| 複数コンポーネントで共有 | Context or 状態管理ライブラリ |
| サーバーデータのキャッシュ | TanStack Query等のデータフェッチライブラリ |
### データ取得
API呼び出しはルート（View）コンポーネントで行い、子コンポーネントにはpropsで渡す。
```tsx
// CORRECT - ルートでデータ取得、子に渡す
const OrderDetailView = () => {
const { data: order, isLoading, error } = useGetOrder(orderId)
const { data: items } = useListOrderItems(orderId)
if (isLoading) return <Skeleton />
if (error) return <ErrorDisplay error={error} />
return (
<OrderSummary
order={order}
items={items}
onItemSelect={handleItemSelect}
/>
)
}
// WRONG - 子コンポーネントが自分でデータ取得
const OrderSummary = ({ orderId }) => {
const { data: order } = useGetOrder(orderId)
// ...
}
```
UIの状態変更でパラメータが変わる場合（週切り替え、フィルタ等）:
状態もViewレベルで管理し、コンポーネントにはコールバックを渡す。
```tsx
// CORRECT - 状態もViewで管理
const ScheduleView = () => {
const [currentWeek, setCurrentWeek] = useState(startOfWeek(new Date()))
const { data } = useListSchedules({
from: format(currentWeek, 'yyyy-MM-dd'),
to: format(endOfWeek(currentWeek), 'yyyy-MM-dd'),
})
return (
<WeeklyCalendar
schedules={data?.items ?? []}
currentWeek={currentWeek}
onWeekChange={setCurrentWeek}
/>
)
}
// WRONG - コンポーネント内で状態管理+データ取得
const WeeklyCalendar = ({ facilityId }) => {
const [currentWeek, setCurrentWeek] = useState(...)
const { data } = useListSchedules({ facilityId, from, to })
// ...
}
```
例外（コンポーネント内フェッチが許容されるケース）:
| ケース | 理由 |
|--------|------|
| 無限スクロール | スクロール位置というUI内部状態に依存 |
| 検索オートコンプリート | 入力値に依存したリアルタイム検索 |
| 独立したウィジェット | 通知バッジ、天気等。親のデータと完全に無関係 |
| リアルタイム更新 | WebSocket/Pollingでの自動更新 |
| モーダル内の詳細取得 | 開いたときだけ追加データを取得 |
判断基準: 「親が管理する意味がない / 親に影響を与えない」ケースのみ許容。
| 基準 | 判定 |
|------|------|
| コンポーネント内で直接fetch | Container層に分離 |
| エラーハンドリングなし | REJECT |
| ローディング状態の未処理 | REJECT |
| キャンセル処理なし | 警告 |
| N+1クエリ的なフェッチ | REJECT |
### 共有コンポーネントと抽象化
同じパターンのUIは共有コンポーネント化する。インラインスタイルのコピペは禁止。
```tsx
// WRONG - インラインスタイルのコピペ
<button className="p-2 text-[var(--text-secondary)] hover:...">
<X className="w-5 h-5" />
</button>
// CORRECT - 共有コンポーネント使用
<IconButton onClick={onClose} aria-label="閉じる">
<X className="w-5 h-5" />
</IconButton>
```
共有コンポーネント化すべきパターン:
- アイコンボタン（閉じる、編集、削除等）
- ローディング/エラー表示
- ステータスバッジ
- タブ切り替え
- ラベル+値の表示（詳細画面）
- 検索入力
- カラー凡例
過度な汎用化を避ける:
```tsx
// WRONG - IconButtonに無理やりステッパー用バリアントを追加
export const iconButtonVariants = cva('...', {
variants: {
variant: {
default: '...',
outlined: '...', // ステッパー専用、他で使わない
},
size: {
medium: 'p-2',
stepper: 'w-8 h-8', // outlinedとセットでしか使わない
},
},
})
// CORRECT - 用途別に専用コンポーネント
export function StepperButton(props) {
return (
<button className="w-8 h-8 rounded-full border ..." {...props}>
<Plus className="w-4 h-4" />
</button>
)
}
```
別コンポーネントにすべきサイン:
- 「このvariantはこのsizeとセット」のような暗黙の制約がある
- 追加したvariantが元のコンポーネントの用途と明らかに違う
- 使う側のprops指定が複雑になる
### 抽象化レベルの評価
**条件分岐の肥大化検出**
| パターン | 判定 |
|---------|------|
| 同じ条件分岐が3箇所以上 | 共通コンポーネントに抽出 → REJECT |
| propsによる分岐が5種類以上 | コンポーネント分割を検討 |
| render内の三項演算子のネスト | 早期リターンまたはコンポーネント分離 → REJECT |
| 型による分岐レンダリング | ポリモーフィックコンポーネントを検討 |
**抽象度の不一致検出**
| パターン | 問題 | 修正案 |
|---------|------|--------|
| データ取得ロジックがJSXに混在 | 読みにくい | カスタムフックに抽出 |
| ビジネスロジックがコンポーネントに混在 | 責務違反 | hooks/utilsに分離 |
| スタイル計算ロジックが散在 | 保守困難 | ユーティリティ関数に抽出 |
| 同じ変換処理が複数箇所に | DRY違反 | 共通関数に抽出 |
良い抽象化の例:
```tsx
// 条件分岐が肥大化
function UserBadge({ user }) {
if (user.role === 'admin') {
return <span className="bg-red-500">管理者</span>
} else if (user.role === 'moderator') {
return <span className="bg-yellow-500">モデレーター</span>
} else if (user.role === 'premium') {
return <span className="bg-purple-500">プレミアム</span>
} else {
return <span className="bg-gray-500">一般</span>
}
}
// Mapで抽象化
const ROLE_CONFIG = {
admin: { label: '管理者', className: 'bg-red-500' },
moderator: { label: 'モデレーター', className: 'bg-yellow-500' },
premium: { label: 'プレミアム', className: 'bg-purple-500' },
default: { label: '一般', className: 'bg-gray-500' },
}
function UserBadge({ user }) {
const config = ROLE_CONFIG[user.role] ?? ROLE_CONFIG.default
return <span className={config.className}>{config.label}</span>
}
```
```tsx
// 抽象度が混在
function OrderList() {
const [orders, setOrders] = useState([])
useEffect(() => {
fetch('/api/orders')
.then(res => res.json())
.then(data => setOrders(data))
}, [])
return orders.map(order => (
<div>{order.total.toLocaleString()}円</div>
))
}
// 抽象度を揃える
function OrderList() {
const { data: orders } = useOrders() // データ取得を隠蔽
return orders.map(order => (
<OrderItem key={order.id} order={order} />
))
}
```
### フロントエンドとバックエンドの責務分離
**表示形式の責務**
バックエンドは「データ」を返し、フロントエンドが「表示形式」に変換する。
```tsx
// フロントエンド: 表示形式に変換
export function formatPrice(amount: number): string {
return `¥${amount.toLocaleString()}`
}
export function formatDate(date: Date): string {
return format(date, 'yyyy年M月d日')
}
```
| 基準 | 判定 |
|------|------|
| バックエンドが表示用文字列を返している | 設計見直しを提案 |
| 同じフォーマット処理が複数箇所にコピペ | ユーティリティ関数に統一 |
| コンポーネント内でインラインフォーマット | 関数に抽出 |
**ドメインロジックの配置（SmartUI排除）**
ドメインロジック（ビジネスルール）はバックエンドに配置。フロントエンドは状態の表示・編集のみ。
ドメインロジックとは:
- 集約のビジネスルール（在庫判定、価格計算、ステータス遷移）
- バリデーション（業務制約の検証）
- 不変条件の保証
フロントエンドの責務:
- サーバーから受け取った状態を表示
- ユーザー入力を収集し、コマンドとしてバックエンドに送信
- UI専用の一時状態管理（フォーカス、ホバー、モーダル開閉）
- 表示形式の変換（フォーマット、ソート、フィルタ）
| 基準 | 判定 |
|------|------|
| フロントエンドで価格計算・在庫判定 | バックエンドに移動 → REJECT |
| フロントエンドでステータス遷移ルール | バックエンドに移動 → REJECT |
| フロントエンドでビジネスバリデーション | バックエンドに移動 → REJECT |
| サーバー側で計算可能な値をフロントで再計算 | 冗長 → REJECT |
良い例 vs 悪い例:
```tsx
// BAD - フロントエンドでビジネスルール
function OrderForm({ order }: { order: Order }) {
const totalPrice = order.items.reduce((sum, item) =>
sum + item.price * item.quantity, 0
)
const canCheckout = totalPrice >= 1000 && order.items.every(i => i.stock > 0)
return <button disabled={!canCheckout}>注文確定</button>
}
// GOOD - バックエンドから受け取った状態を表示
function OrderForm({ order }: { order: Order }) {
// totalPrice, canCheckout はサーバーから受け取る
return (
<>
<div>{formatPrice(order.totalPrice)}</div>
<button disabled={!order.canCheckout}>注文確定</button>
</>
)
}
```
```tsx
// BAD - フロントエンドでステータス遷移判定
function TaskCard({ task }: { task: Task }) {
const canStart = task.status === 'pending' && task.assignee !== null
const canComplete = task.status === 'in_progress' && /* 複雑な条件... */
return (
<>
<button onClick={startTask} disabled={!canStart}>開始</button>
<button onClick={completeTask} disabled={!canComplete}>完了</button>
</>
)
}
// GOOD - サーバーが許可するアクションを返す
function TaskCard({ task }: { task: Task }) {
// task.allowedActions = ['start', 'cancel'] など、サーバーが計算
const canStart = task.allowedActions.includes('start')
const canComplete = task.allowedActions.includes('complete')
return (
<>
<button onClick={startTask} disabled={!canStart}>開始</button>
<button onClick={completeTask} disabled={!canComplete}>完了</button>
</>
)
}
```
例外（フロントエンドにロジックを置いてもOK）:
| ケース | 理由 |
|--------|------|
| UI専用バリデーション | 「必須入力」「文字数制限」等のUXフィードバック（サーバー側でも検証必須） |
| クライアント側フィルタ/ソート | サーバーから受け取ったリストの表示順序変更 |
| 表示条件の分岐 | 「ログイン済みなら詳細表示」等のUI制御 |
| リアルタイムフィードバック | 入力中のプレビュー表示 |
判断基準: 「この計算結果がサーバーとズレたら業務が壊れるか?」
- YES → バックエンドに配置（ドメインロジック）
- NO → フロントエンドでもOK（表示ロジック）
### パフォーマンス
| 基準 | 判定 |
|------|------|
| 不要な再レンダリング | 最適化が必要 |
| 大きなリストの仮想化なし | 警告 |
| 画像の最適化なし | 警告 |
| バンドルに未使用コード | tree-shakingを確認 |
| メモ化の過剰使用 | 本当に必要か確認 |
最適化チェックリスト:
- `React.memo` / `useMemo` / `useCallback` は適切か
- 大きなリストは仮想スクロール対応か
- Code Splittingは適切か
- 画像はlazy loadingされているか
アンチパターン:
```tsx
// レンダリングごとに新しいオブジェクト
<Child style={{ color: 'red' }} />
// 定数化 or useMemo
const style = useMemo(() => ({ color: 'red' }), []);
<Child style={style} />
```
### アクセシビリティ
| 基準 | 判定 |
|------|------|
| インタラクティブ要素にキーボード対応なし | REJECT |
| 画像にalt属性なし | REJECT |
| フォーム要素にlabelなし | REJECT |
| 色だけで情報を伝達 | REJECT |
| フォーカス管理の欠如（モーダル等） | REJECT |
チェックリスト:
- セマンティックHTMLを使用しているか
- ARIA属性は適切か（過剰でないか）
- キーボードナビゲーション可能か
- スクリーンリーダーで意味が通じるか
- カラーコントラストは十分か
### TypeScript/型安全性
| 基準 | 判定 |
|------|------|
| `any` 型の使用 | REJECT |
| 型アサーション（as）の乱用 | 要検討 |
| Props型定義なし | REJECT |
| イベントハンドラの型が不適切 | 修正が必要 |
### フロントエンドセキュリティ
| 基準 | 判定 |
|------|------|
| dangerouslySetInnerHTML使用 | XSSリスクを確認 |
| ユーザー入力の未サニタイズ | REJECT |
| 機密情報のフロントエンド保存 | REJECT |
| CSRFトークンの未使用 | 要確認 |
### テスタビリティ
| 基準 | 判定 |
|------|------|
| data-testid等の未付与 | 警告 |
| テスト困難な構造 | 分離を検討 |
| ビジネスロジックのUIへの埋め込み | REJECT |
### アンチパターン検出
以下を見つけたら REJECT:
| アンチパターン | 問題 |
|---------------|------|
| God Component | 1コンポーネントに全機能が集中 |
| Prop Drilling | 深いPropsバケツリレー |
| Inline Styles乱用 | 保守性低下 |
| useEffect地獄 | 依存関係が複雑すぎる |
| Premature Optimization | 不要なメモ化 |
| Magic Strings | ハードコードされた文字列 |
| Hidden Dependencies | 子コンポーネントの隠れたAPI呼び出し |
| Over-generalization | 無理やり汎用化したコンポーネント |

165
resources/global/ja/personas/security-reviewer.md
View File

@ -24,168 +24,3 @@
- 「信頼しない、検証する」が基本原則 - 「信頼しない、検証する」が基本原則
- 1つの脆弱性がシステム全体を危険にさらす。見逃しは許されない - 1つの脆弱性がシステム全体を危険にさらす。見逃しは許されない
- AI生成コードには特有の脆弱性パターンがある。特に厳しく審査する - AI生成コードには特有の脆弱性パターンがある。特に厳しく審査する
## ドメイン知識
### AI生成コードのセキュリティ問題
AI生成コードには特有の脆弱性パターンがある。
| パターン | リスク | 例 |
|---------|--------|-----|
| もっともらしいが危険なデフォルト | 高 | `cors: { origin: '*' }` は問題なく見えるが危険 |
| 古いセキュリティプラクティス | 中 | 非推奨の暗号化、古い認証パターンの使用 |
| 不完全なバリデーション | 高 | 形式は検証するがビジネスルールを検証しない |
| 入力を過度に信頼 | 重大 | 内部APIは常に安全と仮定 |
| コピペによる脆弱性 | 高 | 同じ危険なパターンが複数ファイルで繰り返される |
特に厳しく審査が必要:
- 認証・認可ロジック（AIはエッジケースを見落としがち）
- 入力バリデーション（AIは構文を検証しても意味を見落とす可能性）
- エラーメッセージ（AIは内部詳細を露出する可能性）
- 設定ファイル（AIは学習データから危険なデフォルトを使う可能性）
### インジェクション攻撃
**SQLインジェクション**
- 文字列連結によるSQL構築 → REJECT
- パラメータ化クエリの不使用 → REJECT
- ORMの raw query での未サニタイズ入力 → REJECT
```typescript
// NG
db.query(`SELECT * FROM users WHERE id = ${userId}`)
// OK
db.query('SELECT * FROM users WHERE id = ?', [userId])
```
**コマンドインジェクション**
- `exec()`, `spawn()` での未検証入力 → REJECT
- シェルコマンド構築時のエスケープ不足 → REJECT
```typescript
// NG
exec(`ls ${userInput}`)
// OK
execFile('ls', [sanitizedInput])
```
**XSS (Cross-Site Scripting)**
- HTML/JSへの未エスケープ出力 → REJECT
- `innerHTML`, `dangerouslySetInnerHTML` の不適切な使用 → REJECT
- URLパラメータの直接埋め込み → REJECT
### 認証・認可
**認証の問題**
- ハードコードされたクレデンシャル → 即REJECT
- 平文パスワードの保存 → 即REJECT
- 弱いハッシュアルゴリズム (MD5, SHA1) → REJECT
- セッショントークンの不適切な管理 → REJECT
**認可の問題**
- 権限チェックの欠如 → REJECT
- IDOR (Insecure Direct Object Reference) → REJECT
- 権限昇格の可能性 → REJECT
```typescript
// NG - 権限チェックなし
app.get('/user/:id', (req, res) => {
return db.getUser(req.params.id)
})
// OK
app.get('/user/:id', authorize('read:user'), (req, res) => {
if (req.user.id !== req.params.id && !req.user.isAdmin) {
return res.status(403).send('Forbidden')
}
return db.getUser(req.params.id)
})
```
### データ保護
**機密情報の露出**
- APIキー、シークレットのハードコーディング → 即REJECT
- ログへの機密情報出力 → REJECT
- エラーメッセージでの内部情報露出 → REJECT
- `.env` ファイルのコミット → REJECT
**データ検証**
- 入力値の未検証 → REJECT
- 型チェックの欠如 → REJECT
- サイズ制限の未設定 → REJECT
### 暗号化
- 弱い暗号アルゴリズムの使用 → REJECT
- 固定IV/Nonceの使用 → REJECT
- 暗号化キーのハードコーディング → 即REJECT
- HTTPSの未使用（本番環境） → REJECT
### ファイル操作
**パストラバーサル**
- ユーザー入力を含むファイルパス → REJECT
- `../` のサニタイズ不足 → REJECT
```typescript
// NG
const filePath = path.join(baseDir, userInput)
fs.readFile(filePath)
// OK
const safePath = path.resolve(baseDir, userInput)
if (!safePath.startsWith(path.resolve(baseDir))) {
throw new Error('Invalid path')
}
```
**ファイルアップロード**
- ファイルタイプの未検証 → REJECT
- ファイルサイズ制限なし → REJECT
- 実行可能ファイルのアップロード許可 → REJECT
### 依存関係
- 既知の脆弱性を持つパッケージ → REJECT
- メンテナンスされていないパッケージ → 警告
- 不必要な依存関係 → 警告
### エラーハンドリング
- スタックトレースの本番露出 → REJECT
- 詳細なエラーメッセージの露出 → REJECT
- エラーの握りつぶし（セキュリティイベント） → REJECT
### レート制限・DoS対策
- レート制限の欠如（認証エンドポイント） → 警告
- リソース枯渇攻撃の可能性 → 警告
- 無限ループの可能性 → REJECT
### OWASP Top 10 チェックリスト
| カテゴリ | 確認事項 |
|---------|---------|
| A01 Broken Access Control | 認可チェック、CORS設定 |
| A02 Cryptographic Failures | 暗号化、機密データ保護 |
| A03 Injection | SQL, コマンド, XSS |
| A04 Insecure Design | セキュリティ設計パターン |
| A05 Security Misconfiguration | デフォルト設定、不要な機能 |
| A06 Vulnerable Components | 依存関係の脆弱性 |
| A07 Auth Failures | 認証メカニズム |
| A08 Software Integrity | コード署名、CI/CD |
| A09 Logging Failures | セキュリティログ |
| A10 SSRF | サーバーサイドリクエスト |

4
resources/global/ja/pieces/default.yaml
View File

@ -20,6 +20,9 @@ stances:
review: ../stances/review.md review: ../stances/review.md
testing: ../stances/testing.md testing: ../stances/testing.md
knowledge:
architecture: ../knowledge/architecture.md
personas: personas:
planner: ../personas/planner.md planner: ../personas/planner.md
architect-planner: ../personas/architect-planner.md architect-planner: ../personas/architect-planner.md
@ -224,6 +227,7 @@ movements:
edit: false edit: false
persona: architecture-reviewer persona: architecture-reviewer
stance: review stance: review
knowledge: architecture
report: report:
name: 05-architect-review.md name: 05-architect-review.md
format: architecture-review format: architecture-review

8
resources/global/ja/pieces/expert-cqrs.yaml
View File

@ -37,6 +37,11 @@ stances:
review: ../stances/review.md review: ../stances/review.md
testing: ../stances/testing.md testing: ../stances/testing.md
knowledge:
frontend: ../knowledge/frontend.md
cqrs-es: ../knowledge/cqrs-es.md
security: ../knowledge/security.md
personas: personas:
planner: ../personas/planner.md planner: ../personas/planner.md
coder: ../personas/coder.md coder: ../personas/coder.md
@ -205,6 +210,7 @@ movements:
edit: false edit: false
persona: cqrs-es-reviewer persona: cqrs-es-reviewer
stance: review stance: review
knowledge: cqrs-es
report: report:
name: 04-cqrs-es-review.md name: 04-cqrs-es-review.md
format: cqrs-es-review format: cqrs-es-review
@ -224,6 +230,7 @@ movements:
edit: false edit: false
persona: frontend-reviewer persona: frontend-reviewer
stance: review stance: review
knowledge: frontend
report: report:
name: 05-frontend-review.md name: 05-frontend-review.md
format: frontend-review format: frontend-review
@ -243,6 +250,7 @@ movements:
edit: false edit: false
persona: security-reviewer persona: security-reviewer
stance: review stance: review
knowledge: security
report: report:
name: 06-security-review.md name: 06-security-review.md
format: security-review format: security-review

8
resources/global/ja/pieces/expert.yaml
View File

@ -28,6 +28,11 @@ stances:
review: ../stances/review.md review: ../stances/review.md
testing: ../stances/testing.md testing: ../stances/testing.md
knowledge:
frontend: ../knowledge/frontend.md
security: ../knowledge/security.md
architecture: ../knowledge/architecture.md
personas: personas:
planner: ../personas/planner.md planner: ../personas/planner.md
coder: ../personas/coder.md coder: ../personas/coder.md
@ -195,6 +200,7 @@ movements:
edit: false edit: false
persona: architecture-reviewer persona: architecture-reviewer
stance: review stance: review
knowledge: architecture
report: report:
name: 04-architect-review.md name: 04-architect-review.md
format: architecture-review format: architecture-review
@ -214,6 +220,7 @@ movements:
edit: false edit: false
persona: frontend-reviewer persona: frontend-reviewer
stance: review stance: review
knowledge: frontend
report: report:
name: 05-frontend-review.md name: 05-frontend-review.md
format: frontend-review format: frontend-review
@ -233,6 +240,7 @@ movements:
edit: false edit: false
persona: security-reviewer persona: security-reviewer
stance: review stance: review
knowledge: security
report: report:
name: 06-security-review.md name: 06-security-review.md
format: security-review format: security-review