ljwx-children/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Gold Template is a production-ready project template showcasing best practices for Claude Code integration, GitHub automation, and modern Python development workflows. This is a meta-template - a template for creating new projects with comprehensive tooling, documentation, and automation built-in.

Key Purpose: Demonstrate and provide a starting point for:

• Claude Code-assisted development
• GitHub Projects integration with custom fields
• Automated testing and CI/CD
• Custom Claude Code skills
• SDLC documentation management

Technology Stack

Core

• Python 3.11+ - Primary language
• FastAPI - Web framework (for actual applications built from this template)
• SQLAlchemy 2.0 - ORM with async support
• SQLite + aiosqlite - Database

Development Tools

• Testing: pytest, pytest-cov, pytest-asyncio, pytest-mock
• Code Quality: black (formatter), flake8 (linter), mypy (type checker)
• Security: bandit, safety
• HTTP Client: httpx, aiohttp

Automation

• GitHub Actions - CI/CD pipelines
• GitHub CLI - Repository automation
• Custom Scripts - Project setup, token management, field configuration

Quick Start Commands

Initial Setup

# One-time setup (creates venv, installs dependencies, configures environment)
./scripts/setup.sh

# Configure GitHub token (required for GitHub Projects integration)
./scripts/setup-token.sh

Development

# Start development server (if building an app from this template)
./scripts/dev.sh
# Runs: uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

# Run full test suite
./scripts/test.sh
# Runs: black, flake8, mypy, pytest with coverage

Code Quality

# Format code
black .

# Lint code
flake8 .

# Type check
mypy src/

# Run tests with coverage
pytest --cov=src --cov-report=html

GitHub Integration

# Setup GitHub Project custom fields
python3 scripts/setup-project-fields.py --project-number <N> --owner @me

# Generate progress report
python3 scripts/generate-progress-report.py --project-id <ID>

# Add date fields to project
python3 scripts/add-date-fields.py --project-number <N> --owner @me

Architecture and Structure

High-Level Architecture

This template provides three main layers:

1. Claude Code Skills Layer (.claude/skills/)

   • Executable Python scripts that integrate with Claude Code
   • Each skill is self-contained with its own README and dependencies
   • Skills can be invoked manually or as part of workflows

2. GitHub Automation Layer (.github/workflows/, scripts/)

   • CI/CD pipelines for testing, security scanning, and deployment
   • Python scripts for GitHub API integration (Projects, Issues, Fields)
   • Token management and authentication helpers

3. Documentation Layer (docs/)

   • SDLC-aligned documentation (requirements → design → development → testing → deployment → operations)
   • Workflow guides and best practices
   • Template files for issues and PRs

Key Architectural Patterns

Claude Code Skills Architecture:

• Each skill in .claude/skills/<skill-name>/ contains:
  • skill.json - Metadata and configuration
  • <skill>.py - Main implementation (Python)
  • README.md - Usage documentation
  • Skills are designed to be run as standalone tools OR integrated with Claude Code

GitHub Token Management:

• Multi-source token resolution in priority order:
  1. GitHub CLI (gh auth token)
  2. Environment variable (GITHUB_TOKEN)
  3. System keychain (macOS Keychain, Linux pass)
  4. .env file
• Centralized in scripts/get-github-token.py for reuse

Project Fields Pattern:

• Custom fields defined in YAML templates (config/project-fields-template.yml)
• Applied via GraphQL API using scripts/setup-project-fields.py
• Fields are project-level (not repository-level), enabling cross-repo tracking

Directory Structure

gold-template/
├── .claude/                      # Claude Code configuration
│   ├── skills/                   # Custom Claude Code skills (4 implemented)
│   │   ├── code-review/         # Security + quality + type checking
│   │   ├── test-generator/      # Auto-generate pytest tests
│   │   ├── refactor-assistant/  # Code smell detection
│   │   └── api-designer/        # OpenAPI spec generation
│   └── hooks/                    # Git hooks (pre-commit, pre-push)
├── .github/
│   ├── workflows/               # CI/CD automation
│   │   ├── ci.yml              # Test, lint, security scan
│   │   ├── claude-assistant.yml # Claude-powered PR analysis
│   │   └── sync-projects.yml   # Sync issues to Projects
│   └── ISSUE_TEMPLATE/         # Issue templates (bug, feature, task)
├── scripts/                     # Automation scripts
│   ├── setup.sh                # Initial project setup
│   ├── dev.sh                  # Start development server
│   ├── test.sh                 # Run full test suite
│   ├── setup-token.sh          # GitHub token configuration
│   ├── setup-project-fields.py # Configure GitHub Project fields
│   └── generate-progress-report.py # Generate progress reports
├── docs/                        # SDLC documentation
│   ├── 01-requirements/        # BRD, PRD templates
│   ├── 02-design/              # Architecture, API design
│   ├── 03-development/         # Development guides
│   ├── 04-testing/             # Test plans, test cases
│   ├── 05-deployment/          # Deployment guides
│   ├── 06-operations/          # Operations runbooks
│   └── workflows/              # Process documentation
├── src/                         # Application source (empty in template)
└── tests/                       # Test files

Claude Code Skills

This template includes 4 production-ready skills:

1. Code Review (code-review)

Purpose: Automated code review with security scanning, linting, and type checking

Command:

python3 .claude/skills/code-review/review.py [--target PATH] [--type TYPE] [--output FILE]

Key Features:

• Security scan with Bandit (SQL injection, XSS, hardcoded secrets)
• Code quality with Flake8 (PEP 8, complexity)
• Type checking with MyPy
• Custom best practices (logging, TODO detection)

2. Test Generator (test-generator)

Purpose: Generate pytest test cases by analyzing source code

Command:

python3 .claude/skills/test-generator/generate.py [--target PATH] [--run-tests]

Key Features:

• Analyzes functions, classes, methods
• Generates AAA (Arrange-Act-Assert) pattern tests
• Identifies mock requirements
• Creates edge cases and error handling tests

3. Refactor Assistant (refactor-assistant)

Purpose: Detect code smells and suggest refactoring opportunities

Command:

python3 .claude/skills/refactor-assistant/assistant.py [--target PATH] [--complexity-threshold N]

Key Features:

• Detects 10+ code smell patterns
• McCabe complexity analysis
• Duplicate code detection
• Actionable refactoring suggestions

4. API Designer (api-designer)

Purpose: Analyze code and generate OpenAPI specifications

Command:

python3 .claude/skills/api-designer/design.py [--target PATH] [--format json|yaml] [--interactive]

Key Features:

• FastAPI/Flask/Django support
• OpenAPI 3.0 spec generation
• Interactive design wizard
• RESTful best practices

GitHub Projects Integration

Custom Fields System

The template includes a comprehensive custom fields configuration for GitHub Projects:

Standard Fields:

• Phase: Requirements, Design, Development, Testing, Deployment, Operations
• Doc Type: BRD, PRD, Design, API, Test Case, Test Report, Deployment, Operations
• Document Priority: P0-Critical, P1-High, P2-Medium, P3-Low
• Document Status: Draft, Review, Approved, Implemented, Archived
• Progress: 0-100 percentage
• Date Fields: Start Date, Target Date, Due Date, Actual Completion Date

Setup:

# Preview changes (dry-run)
python3 scripts/setup-project-fields.py --project-number 1 --owner @me --dry-run

# Apply configuration
python3 scripts/setup-project-fields.py --project-number 1 --owner @me

Important: Fields are project-level, not repo-level. A single project can track issues across multiple repositories.

Timeline/Gantt Chart View

The template supports timeline/Gantt chart visualization:

1. Create a Timeline view in GitHub Projects
2. Configure: Start date = Start Date, End date = Target Date
3. Group by: Phase or Assignees
4. Color by: Document Priority

Generate progress reports:

python3 scripts/generate-progress-report.py --project-id PVT_kwDO... --output report.md

Development Workflow with Claude Code

Typical Development Cycle

1. Explore: "Analyze the project structure and identify where to add feature X"
2. Design: "Design an approach for implementing feature X that follows the existing patterns"
3. Implement: "Implement the feature based on our design discussion"
4. Test: "Generate comprehensive tests for the new feature" (use test-generator skill)
5. Review: "Review the changes for security and quality issues" (use code-review skill)
6. Document: "Update the relevant documentation in docs/"

Best Practices for Claude Interaction

Provide Specific Context:

❌ "Fix this bug"
✅ "The function at src/auth.py:45 raises an uncaught KeyError when the token is expired.
   Please add proper error handling and return a meaningful error response."

Leverage Project Structure:

"I need to add user authentication. Based on the project structure:
1. Where should the auth logic go?
2. What's the existing pattern for database models?
3. How are other endpoints structured?"

Use Skills Explicitly:

"Run the code-review skill on my recent changes and show me any security issues"
"Use the test-generator skill to create tests for the new UserService class"

Testing Strategy

Test Organization

• tests/unit/ - Fast, isolated unit tests
• tests/integration/ - Tests with external dependencies (DB, API)
• tests/e2e/ - End-to-end user flow tests

Running Tests

# All tests with coverage
pytest --cov=src --cov-report=html

# Specific test category
pytest tests/unit/ -v
pytest tests/integration/ -v

# Watch mode (requires pytest-watch)
ptw -- --cov=src

Coverage Requirements

• Target: >80% overall coverage
• Critical paths: >95% coverage
• HTML report: htmlcov/index.html

CI/CD Pipeline

GitHub Actions Workflows

CI Workflow (.github/workflows/ci.yml):

1. Runs on: Push to main/develop, PRs, manual dispatch
2. Steps: Checkout → Setup Python → Install deps → Lint → Type check → Test → Upload coverage
3. Security scan with Trivy

Claude Assistant Workflow (.github/workflows/claude-assistant.yml):

• Analyzes PRs and generates summaries
• Creates task breakdowns
• Identifies potential issues

Sync Projects Workflow (.github/workflows/sync-projects.yml):

• Syncs issues to GitHub Projects
• Updates custom fields
• Scheduled and on-demand

Environment Configuration

Required Environment Variables

# .env file (copy from .env.example)
SECRET_KEY=<generate-secure-key>          # Application secret
GITHUB_TOKEN=<token-from-gh-cli>          # GitHub API access (optional for most dev)
DATABASE_URL=sqlite+aiosqlite:///./db.sqlite  # Database connection

GitHub Token Setup

Priority Order (automatic detection):

1. GitHub CLI: gh auth token
2. Environment: $GITHUB_TOKEN
3. Keychain: macOS Keychain / Linux pass
4. File: .env

Setup:

# Option 1: Use GitHub CLI (recommended)
gh auth login

# Option 2: Use setup wizard
./scripts/setup-token.sh

# Option 3: Manual
export GITHUB_TOKEN="ghp_xxxx"

Documentation System

SDLC-Aligned Structure

The docs/ directory follows the Software Development Life Cycle:

1. Requirements (docs/01-requirements/) - BRD, PRD, user stories
2. Design (docs/02-design/) - Architecture, API specs, data models
3. Development (docs/03-development/) - Coding standards, setup guides
4. Testing (docs/04-testing/) - Test plans, test cases, test reports
5. Deployment (docs/05-deployment/) - Deployment guides, runbooks
6. Operations (docs/06-operations/) - Monitoring, maintenance, troubleshooting

Keeping Documentation Updated

When making changes:

1. Update relevant markdown files in docs/
2. Use the doc-updater skill: python3 .claude/skills/doc-updater/update.py
3. Ensure API docs are regenerated (if using FastAPI, visit /docs endpoint)

Common Development Tasks

Adding a New Feature

1. Create issue from template: gh issue create --template claude-assisted-task.md
2. Create branch: git checkout -b feature/feature-name
3. Use Claude Code to design and implement
4. Run tests: ./scripts/test.sh
5. Create PR: gh pr create --fill

Creating a Custom Skill

1. Create directory: .claude/skills/my-skill/
2. Add skill.json:

{
  "name": "my-skill",
  "version": "1.0.0",
  "description": "Skill description",
  "command": "python3 .claude/skills/my-skill/run.py"
}

3. Implement run.py
4. Add README.md with usage examples

Configuring GitHub Project Fields

1. Get project number: gh project list --owner @me
2. Preview: python3 scripts/setup-project-fields.py --project-number N --owner @me --dry-run
3. Apply: python3 scripts/setup-project-fields.py --project-number N --owner @me
4. Customize: Edit config/project-fields-template.yml

Important Implementation Details

Async Patterns

• All database operations use async/await
• Use async with for database sessions
• FastAPI handles async endpoint execution automatically

Token Management Security

• Never commit tokens to git
• .gitignore includes .env, token files
• Use system keychains when possible
• Rotate tokens regularly

Skills Implementation Pattern

Skills follow a common pattern:

# 1. Parse CLI arguments
# 2. Detect target files (git diff or --target)
# 3. Run analysis tools
# 4. Parse and format results
# 5. Display summary with color coding
# 6. Optionally save to file

GitHub GraphQL API Usage

• Project fields use GraphQL (not REST API)
• Queries require organization/user IDs
• Field IDs are opaque strings (fetch before update)
• See scripts/setup-project-fields.py for examples

Using This Template for New Projects

Method 1: GitHub Template

1. Click "Use this template" on GitHub
2. Create new repository
3. Clone and run ./scripts/setup.sh

Method 2: Manual Clone

git clone https://github.com/yourusername/gold-template.git my-project
cd my-project
rm -rf .git
git init
git add .
git commit -m "Initial commit from gold-template"

Method 3: Cherry-Pick Components

Copy desired components to existing project:

cp -r gold-template/.claude your-project/
cp -r gold-template/.github your-project/
cp -r gold-template/scripts your-project/
cp -r gold-template/docs your-project/

Customization Checklist

• Update README.md with your project details
• Edit .claude/CLAUDE.md with project-specific guidance
• Customize GitHub issue templates
• Adjust CI/CD workflows for your tech stack
• Configure GitHub Project fields to match your workflow
• Update skill configurations if needed
• Remove unused documentation templates

Key Files Reference

Configuration:

• .env.example - Environment variable template
• requirements.txt - Python dependencies
• config/project-fields-template.yml - GitHub Project fields definition

Entry Points:

• scripts/setup.sh - Initial setup
• scripts/dev.sh - Development server
• scripts/test.sh - Test runner
• scripts/setup-token.sh - Token configuration wizard

Documentation:

• README.md - Project overview and quickstart
• QUICKSTART.md - 5-minute getting started guide
• OPTIMIZATION-ROADMAP.md - 3-phase improvement plan (8-10 weeks)
• TODO.md - Remaining tasks and future work

Guides:

• TOKEN-SETUP-QUICKSTART.md - GitHub token setup
• SETUP-FIELDS.md - Project fields setup
• TIMELINE-GANTT-QUICKSTART.md - Timeline view configuration
• PROJECT-MANAGEMENT-SUMMARY.md - Complete project management approach

---

Template Version: 1.0.0 Last Updated: 2024-12-30 Maintained By: Template Contributors

Development Principles:

• Simplicity over complexity
• Automation over manual processes
• Documentation-driven development
• Claude Code-first approach
• Quality through automation