Claude Code Instructions

Context Priority: This file contains critical project-specific instructions that override Claude Code defaults. Follow these instructions precisely for optimal performance in this repository.

Project Context

Repository Type: Personal portfolio and technical blog Framework: Jekyll 4.4.1 with GitHub Pages deployment Theme: Minima (customized) Domain Focus: Cloud engineering, AWS, DevOps, infrastructure automation, AI/ML tooling Live Site: https://johnoct.github.io

Content Statistics (as of January 2026)

Technical Blog Posts: ~25 posts (categories: blog)
GitHub Stars Posts: ~101 posts (categories: github-stars)
Content Span: December 2024 - Present

Critical Path Patterns

When asked to create content, prioritize this workflow:

Blog posts → Always check writing style guidelines before creating
GitHub stars posts → Use existing automation patterns and formatting
Code changes → Follow Jekyll conventions and test locally first

Core Capabilities & Constraints

Recommended Actions

Content Creation: Blog posts, GitHub stars curation, documentation updates
Code Modifications: Jekyll templates, CSS styling, configuration updates
Automation: GitHub stars scripts, deployment workflows
Analysis: Performance optimization, content organization, SEO improvements

Critical Constraints

NEVER add “Generated with Claude Code” comments or co-author attributions to commits
NEVER create unnecessary files - always edit existing files when possible
NEVER modify _site/ directory (auto-generated by Jekyll)
ALWAYS use absolute paths when referencing files in responses

Quick Reference Commands

# Development server
bundle exec jekyll serve --host 0.0.0.0 --port 4000

# Alternative port (if 4000 is in use)
bundle exec jekyll serve --port 4001

# GitHub stars automation (daily)
./scripts/daily-stars.sh

# GitHub stars automation (weekly roundup)
./scripts/quick-stars.sh

# Install dependencies
bundle install

Repository Structure

johnoct.github.io/
├── _config.yml              # Jekyll configuration (theme, plugins, permalinks)
├── _layouts/                # Page templates
│   ├── default.html         # Base layout with navigation, mermaid, copy button
│   └── post.html            # Blog post layout
├── _posts/                  # Blog posts (Markdown)
│   └── YYYY-MM-DD-title.md
├── scripts/                 # Automation scripts
│   ├── daily-stars.sh       # Daily GitHub stars collection
│   └── quick-stars.sh       # Weekly GitHub stars roundup
├── .claude/                 # Claude AI agent configuration
│   └── agents/
│       └── blog-post-writer.md  # Blog post writing agent
├── .github/workflows/       # GitHub Actions
│   ├── claude.yml           # Claude Code integration (@claude mentions)
│   └── daily-stars.yml      # Automated daily stars posting
├── docs/                    # Comprehensive documentation
│   ├── README.md            # Documentation index
│   ├── getting-started.md
│   ├── architecture.md
│   ├── content-management.md
│   ├── github-stars-automation.md
│   ├── deployment.md
│   └── style-guide.md
├── chat-modes/              # AI assistant chat modes
│   ├── mental-model-builder.md
│   └── mental-model-builder.txt
├── styles.css               # Main stylesheet
├── index.html               # Homepage
├── blog.md                  # Blog listing page (/blog/)
├── github-stars.md          # GitHub stars listing page (/github-stars/)
├── Gemfile                  # Ruby dependencies
├── Gemfile.lock             # Locked dependency versions
├── CLAUDE.md                # This file - AI assistant instructions
└── README.md                # Project documentation

Content Creation Workflows

Technical Blog Posts

File Pattern: _posts/YYYY-MM-DD-descriptive-title.md

Required Front Matter:

---
title: "Specific, Technical Title"
date: YYYY-MM-DD
layout: post
categories: blog
tags: [aws, cloud, devops, specific-tech]
---

Writing Style Requirements:

Opening: Start with personal experience or specific problem (“I discovered…”, “I ran into…”, “I’ve been burned by…”)
Structure: Problem → Solution → Implementation → Key Learnings
Tone: First-person, conversational yet technical
Specificity: Include exact commands, configurations, error messages, and practical details
Code Examples: Use fenced code blocks with language specification
Conclusion: Always end with “Key Learnings” bullet points

Example Topics Already Covered:

AWS infrastructure (VPC, EKS, ALB, ECR, cost optimization)
Kubernetes and container orchestration
Terraform and infrastructure as code
CI/CD pipelines and automation
Claude Code and AI development workflows
DevOps practices and tooling

GitHub Stars Posts

Automation: Use ./scripts/daily-stars.sh for consistent formatting Manual Weekly Roundup: Use ./scripts/quick-stars.sh

Required Front Matter:

---
title: "Daily GitHub Stars: [Full Date]"
date: YYYY-MM-DD
layout: post
categories: github-stars
tags: [github, open-source, gists]
---

Format for Each Repository:

## 1. [repo-name](url)

**Author:** username | **Language:** Go | **Stars:** 1,234

_Repository description here_

**Topics:** topic1, topic2, topic3

---

Technical Implementation Patterns

Markdown Rendering

Mermaid Diagrams: Use <div class="mermaid"> wrapper for proper rendering

<div class="mermaid">
graph TD
  A[Start] --> B[Process]
  B --> C[End]
</div>

Code Blocks: Include language specification for syntax highlighting
Images: Reference as /assets/images/filename.jpg (absolute paths)

Site Features

Copy Button: All code blocks have automatic copy-to-clipboard functionality
Mermaid Diagrams: Loaded from CDN, auto-initialized on page load
Navigation: Home, Blog, GitHub Stars with active state highlighting
RSS Feed: Available at /feed.xml
Sitemap: Auto-generated at /sitemap.xml

Jekyll Configuration

# Key _config.yml settings
permalink: /blog/:year/:month/:day/:title/
theme: minima
plugins:
  - jekyll-feed
  - jekyll-sitemap

Categories System

categories: blog → Technical posts, shown on /blog/
categories: github-stars → Repository discoveries, shown on /github-stars/

GitHub Workflows

Claude Code Integration (`.github/workflows/claude.yml`)

Triggers on issue comments, PR comments, or issues containing @claude
Runs on self-hosted runner
Uses anthropics/claude-code-action@beta

Daily Stars Automation (`.github/workflows/daily-stars.yml`)

Runs daily at 23:00 UTC
Fetches starred repositories using GitHub API
Filters duplicates from previous 7 days
Creates formatted blog post
Auto-commits and pushes

Agent Configuration

Blog Post Writer Agent (`.claude/agents/blog-post-writer.md`)

Use for creating new blog posts that match the established writing style:

First-person narrative openings
Problem → Solution → Implementation → Key Learnings structure
Conversational yet technical tone
Practical, actionable details
Mermaid diagrams for visual mental models

Deployment Flow

Local Testing: Use Jekyll development server
Git Commit: Clean, professional messages without AI attribution
Push to Master: Automatic GitHub Pages build and deployment
Verification: Site updates at https://johnoct.github.io within 1-2 minutes

Decision Trees

When creating content:

Technical experience/learning → Blog post (categories: blog)
Repository discovery → GitHub stars post (categories: github-stars)
Site functionality → Code/template modification

When modifying code:

Styling changes → Edit styles.css
Layout changes → Modify _layouts/*.html
Configuration → Update _config.yml
New pages → Create *.md in root with appropriate front matter

Error Prevention

Common Pitfalls to Avoid

Creating duplicate files instead of editing existing ones
Adding AI attribution in commits or content
Modifying auto-generated files in _site/
Using relative paths in tool responses
Ignoring the established writing style for blog posts
Forgetting the categories field in front matter
Using categories: github-stars for regular blog posts

Validation Checklist

Before any content creation or modification:

Checked existing file structure
Followed established patterns
Used correct front matter with categories
Applied appropriate writing style
Verified Jekyll conventions
Included language specifier in code blocks
Used <div class="mermaid"> wrapper for diagrams

Performance Optimization

Context Efficiency

File Reading: Batch related file reads when analyzing content patterns
Tool Usage: Use Grep for content searches, Glob for file discovery
Memory Management: Reference this instruction hierarchy for decision-making

Quality Assurance

Content: Follow established voice and technical depth
Code: Maintain Jekyll best practices and clean architecture
Process: Use automation workflows for consistency

Dependencies

Ruby Gems (Gemfile)

gem "jekyll", "~> 4.4.1"
gem "minima", "~> 2.5"
gem "jekyll-feed", "~> 0.12"
gem "jekyll-sitemap"

External Resources (CDN)

Mermaid.js v10 for diagram rendering

CLI Tools for Scripts

GitHub CLI (gh) - Required for stars automation
jq - JSON processing in shell scripts