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
Domain Focus: Cloud engineering, AWS, DevOps, infrastructure automation
Content Types: Technical blog posts (categories: blog) and repository discovery posts (categories: github-stars)

Critical Path Patterns

When asked to create content, prioritize this workflow:

1. Blog posts → Always check writing style guidelines before creating
2. GitHub stars posts → Use existing automation patterns and formatting
3. 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
bundle exec jekyll serve --port 4001

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

File System Navigation

Content Creation Paths

• Blog Posts: _posts/YYYY-MM-DD-title.md
• Pages: *.md files in root directory
• Images: assets/images/filename.jpg
• Styles: styles.css (main stylesheet)

Configuration Files

• Jekyll Config: _config.yml
• Dependencies: Gemfile, Gemfile.lock
• Layouts: _layouts/default.html, _layouts/post.html

Automation Scripts

• Daily Stars: scripts/daily-stars.sh (fetches and creates daily GitHub stars posts)
• Quick Stars: scripts/quick-stars.sh (manual execution helper)

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
• Structure: Problem → Solution → Implementation → Key Learnings
• Tone: First-person, conversational yet technical
• Specificity: Include exact commands, configurations, and practical details
• Conclusion: Always end with “Key Learnings” bullet points

GitHub Stars Posts

Automation: Use ./scripts/daily-stars.sh for consistent formatting Manual Creation: Follow existing post patterns in _posts/*github-stars.md

Required Front Matter:

---
title: "GitHub Stars of the Week/Day: [Date Range]"
date: YYYY-MM-DD
layout: post
categories: github-stars
tags: [automation, open-source, github]
---

Technical Implementation Patterns

Markdown Rendering

• Mermaid Diagrams: Use <div class="mermaid"> wrapper for proper rendering
• Code Blocks: Include language specification for syntax highlighting
• Images: Reference as /assets/images/filename.jpg (absolute paths)

Jekyll Conventions

• Categories: Control page display (blog vs github-stars)
• Tags: Improve discoverability and organization
• Layouts: post for articles, default for pages

Deployment Flow

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

Context Memory Patterns

Agent Workflows

• Blog Creation: Use @agent-blog-post-writer → @agent-git-manager pipeline
• Content Review: Always verify against established writing style
• Automation: Prefer existing scripts over manual content creation

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

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

Validation Checklist

Before any content creation or modification:

• Checked existing file structure
• Followed established patterns
• Used correct front matter
• Applied appropriate writing style
• Verified Jekyll conventions
• Planned deployment strategy

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