mirror of
https://github.com/LerianStudio/ring
synced 2026-04-21 13:37:27 +00:00
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
This commit is contained in:
Jefferson Rodrigues
parent
c60b1a95cc
commit
675a4e3029
10 changed files with 213 additions and 17 deletions
38
CLAUDE.md
38
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:**
|
||||
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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+
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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+
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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** |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue