Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

docs: expand Spring Boot skills and add Go microservice example

Affaan Mustafaf375171b1373
diff --git a/README.md b/README.md
index ef78ea3c4..8c6dc3bc6 100644
--- a/README.md
+++ b/README.md
@@ -318,7 +318,8 @@ everything-claude-code/
|-- examples/ # Example configurations and sessions
| |-- CLAUDE.md # Example project-level config
| |-- user-CLAUDE.md # Example user-level config
-| |-- saas-nextjs-CLAUDE.md # Real-world SaaS (Next.js + Supabase + Stripe)
+| |-- saas-nextjs-CLAUDE.md # Real-world SaaS (Next.js + Supabase + Stripe)
+| |-- go-microservice-CLAUDE.md # Real-world Go microservice (gRPC + PostgreSQL)
|
|-- mcp-configs/ # MCP server configurations
| |-- mcp-servers.json # GitHub, Supabase, Vercel, Railway, etc.
diff --git a/examples/go-microservice-CLAUDE.md b/examples/go-microservice-CLAUDE.md
new file mode 100644
index 000000000..62ad81f18
--- /dev/null
+++ b/examples/go-microservice-CLAUDE.md
@@ -0,0 +1,267 @@
+# Go Microservice — Project CLAUDE.md
+
+> Real-world example for a Go microservice with PostgreSQL, gRPC, and Docker.
+> Copy this to your project root and customize for your service.
+
+## Project Overview
+
+**Stack:** Go 1.22+, PostgreSQL, gRPC + REST (grpc-gateway), Docker, sqlc (type-safe SQL), Wire (dependency injection)
+
+**Architecture:** Clean architecture with domain, repository, service, and handler layers. gRPC as primary transport with REST gateway for external clients.
+
+## Critical Rules
+
+### Go Conventions
+
+- Follow Effective Go and the Go Code Review Comments guide
+- Use `errors.New` / `fmt.Errorf` with `%w` for wrapping — never string matching on errors
+- No `init()` functions — explicit initialization in `main()` or constructors
+- No global mutable state — pass dependencies via constructors
+- Context must be the first parameter and propagated through all layers
+
+### Database
+
+- All queries in `queries/` as plain SQL — sqlc generates type-safe Go code
+- Migrations in `migrations/` using golang-migrate — never alter the database directly
+- Use transactions for multi-step operations via `pgx.Tx`
+- All queries must use parameterized placeholders (`$1`, `$2`) — never string formatting
+
+### Error Handling
+
+- Return errors, don't panic — panics are only for truly unrecoverable situations
+- Wrap errors with context: `fmt.Errorf("creating user: %w", err)`
+- Define sentinel errors in `domain/errors.go` for business logic
+- Map domain errors to gRPC status codes in the handler layer
+
+```go
+// Domain layer — sentinel errors
+var (
+ ErrUserNotFound = errors.New("user not found")
+ ErrEmailTaken = errors.New("email already registered")
+)
+
+// Handler layer — map to gRPC status
+func toGRPCError(err error) error {
+ switch {
+ case errors.Is(err, domain.ErrUserNotFound):
+ return status.Error(codes.NotFound, err.Error())
+ case errors.Is(err, domain.ErrEmailTaken):
+ return status.Error(codes.AlreadyExists, err.Error())
+ default:
+ return status.Error(codes.Internal, "internal error")
+ }
+}
+```
+
+### Code Style
+
+- No emojis in code or comments
+- Exported types and functions must have doc comments
+- Keep functions under 50 lines — extract helpers
+- Use table-driven tests for all logic with multiple cases
+- Prefer `struct{}` for signal channels, not `bool`
+
+## File Structure
+
+```
+cmd/
+ server/
+ main.go # Entrypoint, Wire injection, graceful shutdown
+internal/
+ domain/ # Business types and interfaces
+ user.go # User entity and repository interface
+ errors.go # Sentinel errors
+ service/ # Business logic
+ user_service.go
+ user_service_test.go
+ repository/ # Data access (sqlc-generated + custom)
+ postgres/
+ user_repo.go
+ user_repo_test.go # Integration tests with testcontainers
+ handler/ # gRPC + REST handlers
+ grpc/
+ user_handler.go
+ rest/
+ user_handler.go
+ config/ # Configuration loading
+ config.go
+proto/ # Protobuf definitions
+ user/v1/
+ user.proto
+queries/ # SQL queries for sqlc
+ user.sql
+migrations/ # Database migrations
+ 001_create_users.up.sql
+ 001_create_users.down.sql
+```
+
+## Key Patterns
+
+### Repository Interface
+
+```go
+type UserRepository interface {
+ Create(ctx context.Context, user *User) error
+ FindByID(ctx context.Context, id uuid.UUID) (*User, error)
+ FindByEmail(ctx context.Context, email string) (*User, error)
+ Update(ctx context.Context, user *User) error
+ Delete(ctx context.Context, id uuid.UUID) error
+}
+```
+
+### Service with Dependency Injection
+
+```go
+type UserService struct {
+ repo domain.UserRepository
+ hasher PasswordHasher
+ logger *slog.Logger
+}
+
+func NewUserService(repo domain.UserRepository, hasher PasswordHasher, logger *slog.Logger) *UserService {
+ return &UserService{repo: repo, hasher: hasher, logger: logger}
+}
+
+func (s *UserService) Create(ctx context.Context, req CreateUserRequest) (*domain.User, error) {
+ existing, err := s.repo.FindByEmail(ctx, req.Email)
+ if err != nil && !errors.Is(err, domain.ErrUserNotFound) {
+ return nil, fmt.Errorf("checking email: %w", err)
+ }
+ if existing != nil {
+ return nil, domain.ErrEmailTaken
+ }
+
+ hashed, err := s.hasher.Hash(req.Password)
+ if err != nil {
+ return nil, fmt.Errorf("hashing password: %w", err)
+ }
+
+ user := &domain.User{
+ ID: uuid.New(),
+ Name: req.Name,
+ Email: req.Email,
+ Password: hashed,
+ }
+ if err := s.repo.Create(ctx, user); err != nil {
+ return nil, fmt.Errorf("creating user: %w", err)
+ }
+ return user, nil
+}
+```
+
+### Table-Driven Tests
+
+```go
+func TestUserService_Create(t *testing.T) {
+ tests := []struct {
+ name string
+ req CreateUserRequest
+ setup func(*MockUserRepo)
+ wantErr error
+ }{
+ {
+ name: "valid user",
+ req: CreateUserRequest{Name: "Alice", Email: "[email protected]", Password: "secure123"},
+ setup: func(m *MockUserRepo) {
+ m.On("FindByEmail", mock.Anything, "[email protected]").Return(nil, domain.ErrUserNotFound)
+ m.On("Create", mock.Anything, mock.Anything).Return(nil)
+ },
+ wantErr: nil,
+ },
+ {
+ name: "duplicate email",
+ req: CreateUserRequest{Name: "Alice", Email: "[email protected]", Password: "secure123"},
+ setup: func(m *MockUserRepo) {
+ m.On("FindByEmail", mock.Anything, "[email protected]").Return(&domain.User{}, nil)
+ },
+ wantErr: domain.ErrEmailTaken,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ repo := new(MockUserRepo)
+ tt.setup(repo)
+ svc := NewUserService(repo, &bcryptHasher{}, slog.Default())
+
+ _, err := svc.Create(context.Background(), tt.req)
+
+ if tt.wantErr != nil {
+ assert.ErrorIs(t, err, tt.wantErr)
+ } else {
+ assert.NoError(t, err)
+ }
+ })
+ }
+}
+```
+
+## Environment Variables
+
+```bash
+# Database
+DATABASE_URL=postgres://user:pass@localhost:5432/myservice?sslmode=disable
+
+# gRPC
+GRPC_PORT=50051
+REST_PORT=8080
+
+# Auth
+JWT_SECRET= # Load from vault in production
+TOKEN_EXPIRY=24h
+
+# Observability
+LOG_LEVEL=info # debug, info, warn, error
+OTEL_ENDPOINT= # OpenTelemetry collector
+```
+
+## Testing Strategy
+
+```bash
+/go-test # TDD workflow for Go
+/go-review # Go-specific code review
+/go-build # Fix build errors
+```
+
+### Test Commands
+
+```bash
+# Unit tests (fast, no external deps)
+go test ./internal/... -short -count=1
+
+# Integration tests (requires Docker for testcontainers)
+go test ./internal/repository/... -count=1 -timeout 120s
+
+# All tests with coverage
+go test ./... -coverprofile=coverage.out -count=1
+go tool cover -func=coverage.out # summary
+go tool cover -html=coverage.out # browser
+
+# Race detector
+go test ./... -race -count=1
+```
+
+## ECC Workflow
+
+```bash
+# Planning
+/plan "Add rate limiting to user endpoints"
+
+# Development
+/go-test # TDD with Go-specific patterns
+
+# Review
+/go-review # Go idioms, error handling, concurrency
+/security-scan # Secrets and vulnerabilities
+
+# Before merge
+go vet ./...
+staticcheck ./...
+```
+
+## Git Workflow
+
+- `feat:` new features, `fix:` bug fixes, `refactor:` code changes
+- Feature branches from `main`, PRs required
+- CI: `go vet`, `staticcheck`, `go test -race`, `golangci-lint`
+- Deploy: Docker image built in CI, deployed to Kubernetes
diff --git a/skills/springboot-security/SKILL.md b/skills/springboot-security/SKILL.md
index f9dc6a29e..6ca80d406 100644
--- a/skills/springboot-security/SKILL.md
+++ b/skills/springboot-security/SKILL.md
@@ -42,17 +42,88 @@ public class JwtAuthFilter extends OncePerRequestFilter {
- Use `@PreAuthorize("hasRole('ADMIN')")` or `@PreAuthorize("@authz.canEdit(#id)")`
- Deny by default; expose only required scopes
+```java
+@RestController
+@RequestMapping("/api/admin")
+public class AdminController {
+
+ @PreAuthorize("hasRole('ADMIN')")
+ @GetMapping("/users")
+ public List<UserDto> listUsers() {
+ return userService.findAll();
+ }
+
+ @PreAuthorize("@authz.isOwner(#id, authentication)")
+ @DeleteMapping("/users/{id}")
+ public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
+ userService.delete(id);
+ return ResponseEntity.noContent().build();
+ }
+}
+```
+
## Input Validation
- Use Bean Validation with `@Valid` on controllers
- Apply constraints on DTOs: `@NotBlank`, `@Email`, `@Size`, custom validators
- Sanitize any HTML with a whitelist before rendering
+```java
+// BAD: No validation
+@PostMapping("/users")
+public User createUser(@RequestBody UserDto dto) {
+ return userService.create(dto);
+}
+
+// GOOD: Validated DTO
+public record CreateUserDto(
+ @NotBlank @Size(max = 100) String name,
+ @NotBlank @Email String email,
+ @NotNull @Min(0) @Max(150) Integer age
+) {}
+
+@PostMapping("/users")
+public ResponseEntity<UserDto> createUser(@Valid @RequestBody CreateUserDto dto) {
+ return ResponseEntity.status(HttpStatus.CREATED)
+ .body(userService.create(dto));
+}
+```
+
## SQL Injection Prevention
- Use Spring Data repositories or parameterized queries
- For native queries, use `:param` bindings; never concatenate strings
+```java
+// BAD: String concatenation in native query
+@Query(value = "SELECT * FROM users WHERE name = '" + name + "'", nativeQuery = true)
+
+// GOOD: Parameterized native query
+@Query(value = "SELECT * FROM users WHERE name = :name", nativeQuery = true)
+List<User> findByName(@Param("name") String name);
+
+// GOOD: Spring Data derived query (auto-parameterized)
+List<User> findByEmailAndActiveTrue(String email);
+```
+
+## Password Encoding
+
+- Always hash passwords with BCrypt or Argon2 — never store plaintext
+- Use `PasswordEncoder` bean, not manual hashing
+
+```java
+@Bean
+public PasswordEncoder passwordEncoder() {
+ return new BCryptPasswordEncoder(12); // cost factor 12
+}
+
+// In service
+public User register(CreateUserDto dto) {
+ String hashedPassword = passwordEncoder.encode(dto.password());
+ return userRepository.save(new User(dto.email(), hashedPassword));
+}
+```
+
## CSRF Protection
- For browser session apps, keep CSRF enabled; include token in forms/headers
@@ -70,6 +141,25 @@ http
- Keep `application.yml` free of credentials; use placeholders
- Rotate tokens and DB credentials regularly
+```yaml
+# BAD: Hardcoded in application.yml
+spring:
+ datasource:
+ password: mySecretPassword123
+
+# GOOD: Environment variable placeholder
+spring:
+ datasource:
+ password: ${DB_PASSWORD}
+
+# GOOD: Spring Cloud Vault integration
+spring:
+ cloud:
+ vault:
+ uri: https://vault.example.com
+ token: ${VAULT_TOKEN}
+```
+
## Security Headers
```java
@@ -82,11 +172,63 @@ http
.referrerPolicy(rp -> rp.policy(ReferrerPolicyHeaderWriter.ReferrerPolicy.NO_REFERRER)));
```
+## CORS Configuration
+
+- Configure CORS at the security filter level, not per-controller
+- Restrict allowed origins — never use `*` in production
+
+```java
+@Bean
+public CorsConfigurationSource corsConfigurationSource() {
+ CorsConfiguration config = new CorsConfiguration();
+ config.setAllowedOrigins(List.of("https://app.example.com"));
+ config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE"));
+ config.setAllowedHeaders(List.of("Authorization", "Content-Type"));
+ config.setAllowCredentials(true);
+ config.setMaxAge(3600L);
+
+ UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+ source.registerCorsConfiguration("/api/**", config);
+ return source;
+}
+
+// In SecurityFilterChain:
+http.cors(cors -> cors.configurationSource(corsConfigurationSource()));
+```
+
## Rate Limiting
- Apply Bucket4j or gateway-level limits on expensive endpoints
- Log and alert on bursts; return 429 with retry hints
+```java
+// Using Bucket4j for per-endpoint rate limiting
+@Component
+public class RateLimitFilter extends OncePerRequestFilter {
+ private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();
+
+ private Bucket createBucket() {
+ return Bucket.builder()
+ .addLimit(Bandwidth.classic(100, Refill.intervally(100, Duration.ofMinutes(1))))
+ .build();
+ }
+
+ @Override
+ protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+ FilterChain chain) throws ServletException, IOException {
+ String clientIp = request.getRemoteAddr();
+ Bucket bucket = buckets.computeIfAbsent(clientIp, k -> createBucket());
+
+ if (bucket.tryConsume(1)) {
+ chain.doFilter(request, response);
+ } else {
+ response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
+ response.getWriter().write("{\"error\": \"Rate limit exceeded\"}");
+ }
+ }
+}
+```
+
## Dependency Security
- Run OWASP Dependency Check / Snyk in CI
diff --git a/skills/springboot-verification/SKILL.md b/skills/springboot-verification/SKILL.md
index abec6e8ec..0f2804464 100644
--- a/skills/springboot-verification/SKILL.md
+++ b/skills/springboot-verification/SKILL.md
@@ -42,6 +42,111 @@ Report:
- Total tests, passed/failed
- Coverage % (lines/branches)
+### Unit Tests
+
+Test service logic in isolation with mocked dependencies:
+
+```java
+@ExtendWith(MockitoExtension.class)
+class UserServiceTest {
+
+ @Mock private UserRepository userRepository;
+ @InjectMocks private UserService userService;
+
+ @Test
+ void createUser_validInput_returnsUser() {
+ var dto = new CreateUserDto("Alice", "[email protected]");
+ var expected = new User(1L, "Alice", "[email protected]");
+ when(userRepository.save(any(User.class))).thenReturn(expected);
+
+ var result = userService.create(dto);
+
+ assertThat(result.name()).isEqualTo("Alice");
+ verify(userRepository).save(any(User.class));
+ }
+
+ @Test
+ void createUser_duplicateEmail_throwsException() {
+ var dto = new CreateUserDto("Alice", "[email protected]");
+ when(userRepository.existsByEmail(dto.email())).thenReturn(true);
+
+ assertThatThrownBy(() -> userService.create(dto))
+ .isInstanceOf(DuplicateEmailException.class);
+ }
+}
+```
+
+### Integration Tests with Testcontainers
+
+Test against a real database instead of H2:
+
+```java
+@SpringBootTest
+@Testcontainers
+class UserRepositoryIntegrationTest {
+
+ @Container
+ static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine")
+ .withDatabaseName("testdb");
+
+ @DynamicPropertySource
+ static void configureProperties(DynamicPropertyRegistry registry) {
+ registry.add("spring.datasource.url", postgres::getJdbcUrl);
+ registry.add("spring.datasource.username", postgres::getUsername);
+ registry.add("spring.datasource.password", postgres::getPassword);
+ }
+
+ @Autowired private UserRepository userRepository;
+
+ @Test
+ void findByEmail_existingUser_returnsUser() {
+ userRepository.save(new User("Alice", "[email protected]"));
+
+ var found = userRepository.findByEmail("[email protected]");
+
+ assertThat(found).isPresent();
+ assertThat(found.get().getName()).isEqualTo("Alice");
+ }
+}
+```
+
+### API Tests with MockMvc
+
+Test controller layer with full Spring context:
+
+```java
+@WebMvcTest(UserController.class)
+class UserControllerTest {
+
+ @Autowired private MockMvc mockMvc;
+ @MockBean private UserService userService;
+
+ @Test
+ void createUser_validInput_returns201() throws Exception {
+ var user = new UserDto(1L, "Alice", "[email protected]");
+ when(userService.create(any())).thenReturn(user);
+
+ mockMvc.perform(post("/api/users")
+ .contentType(MediaType.APPLICATION_JSON)
+ .content("""
+ {"name": "Alice", "email": "[email protected]"}
+ """))
+ .andExpect(status().isCreated())
+ .andExpect(jsonPath("$.name").value("Alice"));
+ }
+
+ @Test
+ void createUser_invalidEmail_returns400() throws Exception {
+ mockMvc.perform(post("/api/users")
+ .contentType(MediaType.APPLICATION_JSON)
+ .content("""
+ {"name": "Alice", "email": "not-an-email"}
+ """))
+ .andExpect(status().isBadRequest());
+ }
+}
+```
+
## Phase 4: Security Scan
```bash
@@ -50,10 +155,27 @@ mvn org.owasp:dependency-check-maven:check
# or
./gradlew dependencyCheckAnalyze
-# Secrets (git)
+# Secrets in source
+grep -rn "password\s*=\s*\"" src/ --include="*.java" --include="*.yml" --include="*.properties"
+grep -rn "sk-\|api_key\|secret" src/ --include="*.java" --include="*.yml"
+
+# Secrets (git history)
git secrets --scan # if configured
```
+### Common Security Findings
+
+```
+# Check for System.out.println (use logger instead)
+grep -rn "System\.out\.print" src/main/ --include="*.java"
+
+# Check for raw exception messages in responses
+grep -rn "e\.getMessage()" src/main/ --include="*.java"
+
+# Check for wildcard CORS
+grep -rn "allowedOrigins.*\*" src/main/ --include="*.java"
+```
+
## Phase 5: Lint/Format (optional gate)
```bash