AI Assistant Guidelines for validate-pr-review-app

This document contains common guidelines for AI assistants working on the validate-pr-review-app project. Individual AI-specific documents (like CLAUDE.md, CLINE.md) should reference this guide.

Language

This project uses English for all code comments, documentation, and communication.

Commit Messages

Follow Conventional Commits specification:

Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Common Types

```
feat
```
: A new feature
```
fix
```
: A bug fix
```
docs
```
: Documentation only changes
```
style
```
: Changes that do not affect the meaning of the code
```
refactor
```
: A code change that neither fixes a bug nor adds a feature
```
test
```
: Adding missing tests or correcting existing tests
```
chore
```
: Changes to the build process or auxiliary tools
```
ci
```
: Changes to CI configuration files and scripts

Examples

feat: add GitHub token management via keyring
fix: handle empty configuration file correctly
docs: add function documentation to controller package
chore(deps): update dependency aquaproj/aqua-registry to v4.403.0

Code Validation

After making code changes, always run the following commands to validate and test:

Validation (go vet)

cmdx v

This command runs

go vet ./...

to check for common Go mistakes.

Testing

cmdx t

This command runs all tests in the project.

Both commands should pass before committing changes.

Project Structure

undefined

Package Responsibilities

pkg/cli

Command-line interface layer that handles command parsing, flag processing, and routing to appropriate subcommands.

pkg/config

Configuration management including:

Reading and parsing configuration
Validating configuration structure and constraints
Managing Trust settings for repositories and users
Template processing and validation

pkg/controller

HTTP request handling and webhook processing:

Webhook signature verification and validation
GitHub event parsing (pull request reviews, check suites)
Branch name parsing for merge queue integration
Event routing and processing logic

pkg/validation

Core business logic for PR review validation:

Analyzing PR reviews and approvals
Checking trusted/untrusted users and apps
Validating commit signatures and authorship
Implementing approval requirement logic

pkg/github

GitHub API integration layer:

GraphQL API client for fetching PR data
Pull request and commit information retrieval
Check run creation and status reporting
GitHub App authentication handling

Testing

Test Framework Guidelines

DO NOT use
```
testify
```
for writing tests
DO use
```
google/go-cmp
```
for comparing expected and actual values
Use standard Go testing package (
```
testing
```
) for all tests

Running Tests

Run all tests:

cmdx t

go test -race -covermode=atomic ./...

Run specific package tests:

go test -race -covermode=atomic ./pkg/validation

Generate coverage:
```
./scripts/coverage.sh
```

Dependencies

This project uses:

aqua for tool version management
cmdx for task runner
goreleaser for releases

Code Style Guidelines

Follow standard Go conventions
Use meaningful variable and function names
Add comments for exported functions and types
Keep functions focused and small
Handle errors explicitly
Use context for cancellation and timeouts
Always end files with a newline character

Pull Request Process

Create a feature branch from
```
main
```
Make changes and ensure
```
cmdx v
```
and
```
cmdx t
```
pass
Write clear commit messages following Conventional Commits
Create PR with descriptive title and body
Wait for CI checks to pass
Request review if needed

Important Commands

# Validate code (go vet)
cmdx v

# Run tests
cmdx t

GitHub Actions Integration

The project includes GitHub Actions for:

Testing on multiple platforms
Linting and validation
Release automation
Security scanning

Configuration

Environment Variables

Common Tasks

File Naming Conventions

Go source files: lowercase with underscores (e.g.,
```
parse_line.go
```
)
Test files: append
```
_test.go
```
to the source file name
Internal test files: append
```
_internal_test.go
```
for internal testing

Error Handling

Always check and handle errors explicitly
Use
```
fmt.Errorf
```
with
```
%w
```
for wrapping errors
Add context to errors to aid debugging
Use structured logging with slog

Documentation

Add package-level documentation comments
Document all exported functions, types, and constants
Use examples in documentation where helpful
Keep README and other docs up to date

Resources

Commit Messages

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

feat

: A new feature

fix

: A bug fix

docs

: Documentation only changes

style

: Changes that do not affect the meaning of the code

refactor

: A code change that neither fixes a bug nor adds a feature

test

: Adding missing tests or correcting existing tests

chore

: Changes to the build process or auxiliary tools

ci

: Changes to CI configuration files and scripts

feat: add GitHub token management via keyring
fix: handle empty configuration file correctly
docs: add function documentation to controller package
chore(deps): update dependency aquaproj/aqua-registry to v4.403.0

Package Responsibilities

Command-line interface layer that handles command parsing, flag processing, and routing to appropriate subcommands.

Configuration management including:

Reading and parsing configuration

Validating configuration structure and constraints

Managing Trust settings for repositories and users

Template processing and validation

HTTP request handling and webhook processing:

Webhook signature verification and validation

GitHub event parsing (pull request reviews, check suites)

Branch name parsing for merge queue integration

Event routing and processing logic

Core business logic for PR review validation:

Analyzing PR reviews and approvals

Checking trusted/untrusted users and apps

Validating commit signatures and authorship

Implementing approval requirement logic

GitHub API integration layer:

GraphQL API client for fetching PR data

Pull request and commit information retrieval

Check run creation and status reporting

GitHub App authentication handling

Testing

DO NOT use

testify

for writing tests

DO use

google/go-cmp

for comparing expected and actual values

Use standard Go testing package (

testing

) for all tests

Run all tests:

cmdx t

go test -race -covermode=atomic ./...

Run specific package tests:

go test -race -covermode=atomic ./pkg/validation

Generate coverage:

./scripts/coverage.sh

AI Assistant Guidelines for validate-pr-review-app

Related Skills

Markdown Converter

Nano Banana Pro

1password