From 675a4e3029b70f05cfd3ccfb5e7b9afc2f9d132d Mon Sep 17 00:00:00 2001 From: Jefferson Rodrigues Date: Wed, 17 Dec 2025 12:47:03 -0300 Subject: [PATCH] feat(standards): add TOC to all standards files and improve skill execution - Add Table of Contents to devops.md, frontend.md, golang.md, sre.md, typescript.md - Update CLAUDE.md with Four-File Update Rule and TOC maintenance guidelines - Add checklist for adding/removing sections in standards files - Improve dev-refactor skill to use Skill tool for dev-cycle handoff - Add anti-rationalization patterns for gate execution shortcuts - Add Execution Report sections to dev-cycle, dev-feedback-loop, dev-refactor - Extract gap tracking rationalizations to shared-anti-rationalization.md Generated-by: Claude AI-Model: claude-opus-4-5-20251101 --- CLAUDE.md | 38 ++++++++++-- dev-team/docs/standards/devops.md | 17 ++++++ dev-team/docs/standards/frontend.md | 23 +++++++ dev-team/docs/standards/golang.md | 30 +++++++++ dev-team/docs/standards/sre.md | 16 +++++ dev-team/docs/standards/typescript.md | 24 ++++++++ dev-team/skills/dev-cycle/SKILL.md | 2 + dev-team/skills/dev-feedback-loop/SKILL.md | 2 + dev-team/skills/dev-refactor/SKILL.md | 61 +++++++++++++++---- .../shared-anti-rationalization.md | 17 ++++++ 10 files changed, 213 insertions(+), 17 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 0ee5f592..bee1042b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -39,11 +39,39 @@ When creating or modifying ANY agent in `*/agents/*.md`: ### 5. Standards-Agent Synchronization (ALWAYS CHECK) When modifying standards files (`dev-team/docs/standards/*.md`): -**⛔ THREE-FILE UPDATE RULE:** +**⛔ FOUR-FILE UPDATE RULE:** 1. Edit `dev-team/docs/standards/{file}.md` - Add your `## Section Name` -2. Edit `dev-team/skills/shared-patterns/standards-coverage-table.md` - Add section to agent's index table -3. Edit `dev-team/agents/{agent}.md` - Verify agent references coverage table (NOT inline categories) -4. **All three files in same commit** - Never update one without the others +2. **Update TOC** - Add section to the `## Table of Contents` at the top of the same file +3. Edit `dev-team/skills/shared-patterns/standards-coverage-table.md` - Add section to agent's index table +4. Edit `dev-team/agents/{agent}.md` - Verify agent references coverage table (NOT inline categories) +5. **All files in same commit** - Never update one without the others + +**⛔ TOC MAINTENANCE RULE:** +Every standards file has a `## Table of Contents` section that MUST stay in sync: +- **Format:** `| # | [Section Name](#anchor-link) | Description |` +- **Meta-sections** (Checklist, Standards Compliance) are listed separately below the table +- **Anchor links** use lowercase with hyphens (e.g., `#error-handling-mandatory`) +- **Section count in TOC** MUST match section count in `standards-coverage-table.md` + +**⛔ CHECKLIST: Adding/Removing a Section in Standards Files** +``` +Before committing changes to dev-team/docs/standards/*.md: + +[ ] 1. Did you add/remove a `## Section` in the standards file? +[ ] 2. Did you update the `## Table of Contents` in the SAME file? + - Add/remove row: `| N | [Section Name](#anchor) | Description |` + - Update numbering if needed +[ ] 3. Did you update `dev-team/skills/shared-patterns/standards-coverage-table.md`? + - Find the agent's section index (e.g., "backend-engineer-golang → golang.md") + - Add/remove the section row +[ ] 4. Do the section counts match? + - Count `## ` headers in standards file (excluding meta-sections) + - Count rows in TOC + - Count rows in standards-coverage-table.md for that agent + - ALL THREE must be equal + +If ANY checkbox is NO → Fix before committing. +``` **⛔ AGENT INLINE CATEGORIES ARE FORBIDDEN:** - ✅ Agent has "Sections to Check" referencing `standards-coverage-table.md` @@ -226,7 +254,7 @@ AI models naturally attempt to be "helpful" by making autonomous decisions. This --- -## Assertive Language Reference +## Assertive Language Reference (MANDATORY) **Quick reference for prompt engineering:** diff --git a/dev-team/docs/standards/devops.md b/dev-team/docs/standards/devops.md index a7345ac5..809dc04f 100644 --- a/dev-team/docs/standards/devops.md +++ b/dev-team/docs/standards/devops.md @@ -9,6 +9,23 @@ This file defines the specific standards for DevOps, SRE, and infrastructure. --- +## Table of Contents + +| # | Section | Description | +|---|---------|-------------| +| 1 | [Cloud Provider](#cloud-provider) | AWS, GCP, Azure services | +| 2 | [Infrastructure as Code](#infrastructure-as-code) | Terraform patterns and best practices | +| 3 | [Containers](#containers) | Dockerfile, Docker Compose, .env | +| 4 | [Helm](#helm) | Chart structure and configuration | +| 5 | [Observability](#observability) | Logging and tracing standards | +| 6 | [Security](#security) | Secrets management, network policies | +| 7 | [Makefile Standards](#makefile-standards) | Required commands and patterns | + +**Meta-sections (not checked by agents):** +- [Checklist](#checklist) - Self-verification before deploying + +--- + ## Cloud Provider | Provider | Primary Services | diff --git a/dev-team/docs/standards/frontend.md b/dev-team/docs/standards/frontend.md index 247e169d..4f03bcf1 100644 --- a/dev-team/docs/standards/frontend.md +++ b/dev-team/docs/standards/frontend.md @@ -9,6 +9,29 @@ This file defines the specific standards for frontend development. --- +## Table of Contents + +| # | Section | Description | +|---|---------|-------------| +| 1 | [Framework](#framework) | React 18+, Next.js 14+ | +| 2 | [Libraries & Tools](#libraries--tools) | Core, state, forms, UI, styling, testing | +| 3 | [State Management Patterns](#state-management-patterns) | TanStack Query, Zustand | +| 4 | [Form Patterns](#form-patterns) | React Hook Form + Zod | +| 5 | [Styling Standards](#styling-standards) | TailwindCSS, CSS variables | +| 6 | [Typography Standards](#typography-standards) | Font selection and pairing | +| 7 | [Animation Standards](#animation-standards) | CSS transitions, Framer Motion | +| 8 | [Component Patterns](#component-patterns) | Compound components, error boundaries | +| 9 | [Accessibility (a11y)](#accessibility-a11y) | WCAG 2.1 AA compliance | +| 10 | [Performance](#performance) | Code splitting, image optimization | +| 11 | [Directory Structure](#directory-structure) | Next.js App Router layout | +| 12 | [FORBIDDEN Patterns](#forbidden-patterns) | Anti-patterns to avoid | +| 13 | [Standards Compliance Categories](#standards-compliance-categories) | Categories for dev-refactor | + +**Meta-sections (not checked by agents):** +- [Checklist](#checklist) - Self-verification before submitting code + +--- + ## Framework - React 18+ / Next.js 14+ diff --git a/dev-team/docs/standards/golang.md b/dev-team/docs/standards/golang.md index abecf3a4..f847ed26 100644 --- a/dev-team/docs/standards/golang.md +++ b/dev-team/docs/standards/golang.md @@ -9,6 +9,36 @@ This file defines the specific standards for Go development at Lerian Studio. --- +## Table of Contents + +| # | Section | Description | +|---|---------|-------------| +| 1 | [Version](#version) | Go version requirements | +| 2 | [Core Dependency: lib-commons](#core-dependency-lib-commons-mandatory) | Required foundation library | +| 3 | [Frameworks & Libraries](#frameworks--libraries) | Required packages and versions | +| 4 | [Configuration Loading](#configuration-loading-mandatory) | Environment variable handling | +| 5 | [Telemetry & Observability](#telemetry--observability-mandatory) | OpenTelemetry integration | +| 6 | [Bootstrap Pattern](#bootstrap-pattern-mandatory) | Application initialization | +| 7 | [Data Transformation](#data-transformation-toentityfromentity-mandatory) | ToEntity/FromEntity patterns | +| 8 | [Error Codes Convention](#error-codes-convention-mandatory) | Service-prefixed error codes | +| 9 | [Error Handling](#error-handling) | Error wrapping and checking | +| 10 | [Function Design](#function-design-mandatory) | Single responsibility principle | +| 11 | [Pagination Patterns](#pagination-patterns) | Cursor and page-based pagination | +| 12 | [Testing Patterns](#testing-patterns) | Table-driven tests, edge cases | +| 13 | [Logging Standards](#logging-standards) | Structured logging with lib-commons | +| 14 | [Linting](#linting) | golangci-lint configuration | +| 15 | [Architecture Patterns](#architecture-patterns) | Hexagonal architecture | +| 16 | [Directory Structure](#directory-structure) | Project layout | +| 17 | [Concurrency Patterns](#concurrency-patterns) | Goroutines, channels, errgroup | +| 18 | [DDD Patterns](#ddd-patterns-go-implementation) | Entity, Value Object, Aggregate | +| 19 | [RabbitMQ Worker Pattern](#rabbitmq-worker-pattern) | Async message processing | + +**Meta-sections (not checked by agents):** +- [Standards Compliance Output Format](#standards-compliance-output-format) - Report format for dev-refactor +- [Checklist](#checklist) - Self-verification before submitting code + +--- + ## Version - **Minimum**: Go 1.24 diff --git a/dev-team/docs/standards/sre.md b/dev-team/docs/standards/sre.md index c7eb7fd2..b1252890 100644 --- a/dev-team/docs/standards/sre.md +++ b/dev-team/docs/standards/sre.md @@ -9,6 +9,22 @@ This file defines the specific standards for Site Reliability Engineering and ob --- +## Table of Contents + +| # | Section | Description | +|---|---------|-------------| +| 1 | [Observability Stack](#observability-stack) | Logs, traces, APM tools | +| 2 | [Logging Standards](#logging-standards) | Structured JSON format, log levels | +| 3 | [Tracing Standards](#tracing-standards) | OpenTelemetry configuration | +| 4 | [OpenTelemetry with lib-commons](#opentelemetry-with-lib-commons-mandatory-for-go) | Go service integration | +| 5 | [Structured Logging with lib-common-js](#structured-logging-with-lib-common-js-mandatory-for-typescript) | TypeScript service integration | +| 6 | [Health Checks](#health-checks) | Liveness and readiness probes | + +**Meta-sections (not checked by agents):** +- [Checklist](#checklist) - Self-verification before deploying + +--- + ## Observability Stack | Component | Primary | Alternatives | diff --git a/dev-team/docs/standards/typescript.md b/dev-team/docs/standards/typescript.md index fcc5b4d2..b30df27e 100644 --- a/dev-team/docs/standards/typescript.md +++ b/dev-team/docs/standards/typescript.md @@ -9,6 +9,30 @@ This file defines the specific standards for TypeScript (backend) development. --- +## Table of Contents + +| # | Section | Description | +|---|---------|-------------| +| 1 | [Version](#version) | TypeScript and Node.js versions | +| 2 | [Strict Configuration](#strict-configuration-mandatory) | tsconfig.json requirements | +| 3 | [Frameworks & Libraries](#frameworks--libraries) | Required packages | +| 4 | [Type Safety Rules](#type-safety-rules) | Never use any, branded types | +| 5 | [Zod Validation Patterns](#zod-validation-patterns) | Schema validation | +| 6 | [Dependency Injection](#dependency-injection) | TSyringe patterns | +| 7 | [AsyncLocalStorage for Context](#asynclocalstorage-for-context) | Request context propagation | +| 8 | [Testing Patterns](#testing-patterns) | Type-safe mocks, fixtures | +| 9 | [Error Handling](#error-handling) | Custom error classes | +| 10 | [Function Design](#function-design-mandatory) | Single responsibility principle | +| 11 | [DDD Patterns](#ddd-patterns-typescript-implementation) | Entity, Value Object, Aggregate | +| 12 | [Naming Conventions](#naming-conventions) | Files, interfaces, types | +| 13 | [Directory Structure](#directory-structure-backend) | Project layout | +| 14 | [RabbitMQ Worker Pattern](#rabbitmq-worker-pattern) | Async message processing | + +**Meta-sections (not checked by agents):** +- [Checklist](#checklist) - Self-verification before submitting code + +--- + ## Version - TypeScript 5.0+ diff --git a/dev-team/skills/dev-cycle/SKILL.md b/dev-team/skills/dev-cycle/SKILL.md index 05ba04c5..3143f7ab 100644 --- a/dev-team/skills/dev-cycle/SKILL.md +++ b/dev-team/skills/dev-cycle/SKILL.md @@ -1065,6 +1065,8 @@ After completing all subtasks of a task: ## Execution Report +Base metrics per [shared-patterns/output-execution-report.md](../shared-patterns/output-execution-report.md). + | Metric | Value | |--------|-------| | Duration | Xh Xm Ys | diff --git a/dev-team/skills/dev-feedback-loop/SKILL.md b/dev-team/skills/dev-feedback-loop/SKILL.md index 7697fa24..c165ee30 100644 --- a/dev-team/skills/dev-feedback-loop/SKILL.md +++ b/dev-team/skills/dev-feedback-loop/SKILL.md @@ -412,6 +412,8 @@ TodoWrite tool: ## Execution Report +Base metrics per [shared-patterns/output-execution-report.md](../shared-patterns/output-execution-report.md). + | Metric | Value | |--------|-------| | Tasks Analyzed | N | diff --git a/dev-team/skills/dev-refactor/SKILL.md b/dev-team/skills/dev-refactor/SKILL.md index b3c90e8a..c842a5e4 100644 --- a/dev-team/skills/dev-refactor/SKILL.md +++ b/dev-team/skills/dev-refactor/SKILL.md @@ -33,15 +33,11 @@ This is NOT optional. This is NOT subject to interpretation. This is a HARD RULE ### Anti-Rationalization: Mandatory Gap Principle -| Rationalization | Why It's WRONG | Required Action | -|-----------------|----------------|-----------------| -| "This divergence is too minor to track" | You don't decide what's minor. Standards do. | **Create FINDING-XXX** | -| "Codebase pattern is acceptable alternative" | Alternative ≠ compliant. Ring standards are the baseline. | **Create FINDING-XXX** | -| "Low severity means optional" | Low severity = low priority, NOT optional. | **Create FINDING-XXX** | -| "Cosmetic differences don't count" | Cosmetic = standards compliance. They count. | **Create FINDING-XXX** | -| "This would create too many findings" | Quantity is not your concern. Completeness is. | **Create ALL FINDING-XXX entries** | -| "Team prefers current approach" | Preference ≠ compliance. Document the gap. | **Create FINDING-XXX** | -| "Fixing this adds no value" | You don't assess value. Standards define value. | **Create FINDING-XXX** | +See [shared-patterns/shared-anti-rationalization.md](../shared-patterns/shared-anti-rationalization.md) for: +- **Refactor Gap Tracking** section (mandatory gap principle rationalizations) +- **Gate Execution** section (workflow skip rationalizations) +- **TDD** section (test-first rationalizations) +- **Universal** section (general anti-patterns) ### Verification Rule @@ -942,21 +938,62 @@ docs/refactor/{timestamp}/ **TodoWrite:** Mark "Handoff to dev-cycle" as `in_progress` -**If user approved, use SlashCommand tool with tasks path:** +**If user approved, use Skill tool to invoke dev-cycle directly:** ```yaml -SlashCommand: - command: "/dev-cycle docs/refactor/{timestamp}/tasks.md" +Skill tool: + skill: "dev-cycle" ``` +**⛔ CRITICAL: Pass tasks file path in context:** +After invoking the skill, provide the tasks file location: +- Tasks file: `docs/refactor/{timestamp}/tasks.md` + Where `{timestamp}` is the same timestamp used in Step 9 artifacts. +### Anti-Rationalization: Skill Invocation + +| Rationalization | Why It's WRONG | Required Action | +|-----------------|----------------|-----------------| +| "SlashCommand is equivalent to Skill tool" | SlashCommand is a hint; Skill tool guarantees skill loading | **Use Skill tool, NOT SlashCommand** | +| "User can run /dev-cycle manually" | Manual run risks skill not being loaded | **Invoke Skill tool directly** | +| "dev-cycle will auto-discover tasks" | Explicit path ensures correct file is used | **Pass explicit tasks path** | +| "User approved, I can skip dev-cycle" | Approval = permission to proceed, NOT skip execution | **Invoke Skill tool** | +| "Tasks are saved, job is done" | Saved tasks without execution = incomplete workflow | **Invoke Skill tool** | + +**⛔ HARD GATE: You CANNOT complete dev-refactor without invoking `Skill tool: dev-cycle`.** + +If user approved execution, you MUST: +1. Invoke `Skill tool: dev-cycle` +2. Pass tasks file path: `docs/refactor/{timestamp}/tasks.md` +3. Wait for dev-cycle to complete all 6 gates + +**Skipping this step = SKILL FAILURE.** + dev-cycle executes each REFACTOR-XXX task through 6-gate process. **TodoWrite:** Mark "Handoff to dev-cycle" as `completed` --- +## Execution Report + +Base metrics per [shared-patterns/output-execution-report.md](../shared-patterns/output-execution-report.md). + +| Metric | Value | +|--------|-------| +| Duration | Xm Ys | +| Iterations | N | +| Result | PASS/FAIL/PARTIAL | + +### Refactor-Specific Metrics +| Metric | Value | +|--------|-------| +| Agents Dispatched | N | +| Findings Generated | N | +| Tasks Created | N | +| Artifacts Location | docs/refactors/{date}/ | + ## Output Schema ```yaml diff --git a/dev-team/skills/shared-patterns/shared-anti-rationalization.md b/dev-team/skills/shared-patterns/shared-anti-rationalization.md index a707fa4d..a9eee2c5 100644 --- a/dev-team/skills/shared-patterns/shared-anti-rationalization.md +++ b/dev-team/skills/shared-patterns/shared-anti-rationalization.md @@ -112,6 +112,23 @@ These rationalizations are ALWAYS wrong, regardless of context: | "Previous gate passed, this one will too" | Each gate is independent. No assumptions. | **Execute full gate requirements** | | "Small change, skip full process" | Size doesn't determine requirements. | **Follow complete process** | | "Already tested manually" | Manual testing ≠ gate compliance. | **Execute automated verification** | +| "It's faster to do it directly" | Speed ≠ correct process. The dev-cycle exists for a reason. | **Follow dev-cycle gates. No shortcuts.** | +| "These are simple changes" | Simplicity doesn't justify skipping gates. Simple bugs cause complex incidents. | **ALL gates mandatory regardless of perceived simplicity.** | +| "I know this code well, skip validation" | Familiarity breeds blind spots. Gates catch what you miss. | **Execute ALL gates. No expertise exemption.** | +| "Deadline is tight, skip non-critical gates" | No gate is "non-critical". Each catches different issues. | **ALL gates are mandatory. Negotiate deadline, not quality.** | +| "This is just a hotfix" | Hotfixes are highest-risk changes. They need MORE scrutiny, not less. | **Full dev-cycle for ALL changes including hotfixes.** | + +### Refactor Gap Tracking + +| Rationalization | Why It's WRONG | Required Action | +|-----------------|----------------|-----------------| +| "This divergence is too minor to track" | You don't decide what's minor. Standards do. | **Create FINDING-XXX** | +| "Codebase pattern is acceptable alternative" | Alternative ≠ compliant. Ring standards are the baseline. | **Create FINDING-XXX** | +| "Low severity means optional" | Low severity = low priority, NOT optional. | **Create FINDING-XXX** | +| "Cosmetic differences don't count" | Cosmetic = standards compliance. They count. | **Create FINDING-XXX** | +| "This would create too many findings" | Quantity is not your concern. Completeness is. | **Create ALL FINDING-XXX entries** | +| "Team prefers current approach" | Preference ≠ compliance. Document the gap. | **Create FINDING-XXX** | +| "Fixing this adds no value" | You don't assess value. Standards define value. | **Create FINDING-XXX** | ---