Table of Contents

Problem Statement

As a DevSecOps engineer preparing for AWS Security Specialty certification while building a professional portfolio, I faced a productivity bottleneck: manual, repetitive work that slowed down everything.

The Pain Points

Documentation Was Always Postponed

• Completed AWS infrastructure projects but skipped README files
• Documentation felt like homework, not part of the dev process
• When I did write docs, they were inconsistent and incomplete
• Portfolio project writeups took hours to create from scratch

Git Workflow Was Inconsistent

• Commit messages varied in quality and format
• No standardized branching strategy (new to professional git workflows)
• Manually staging files and writing commit messages was tedious
• Couldn’t remember conventional commit formats without looking them up

Content Creation Was a Barrier

• Blog posts about technical work required hours of writing
• Project writeups for portfolio needed careful structuring
• Wiki documentation for personal reference never happened
• All of this took time away from actual building

The Fundamental Problem: I’m a builder, not a writer. But in DevSecOps, documentation and communication are as important as the code itself. I needed automation that could handle the writing while I focused on building.

Why Traditional Solutions Failed

Static Templates Don’t Work

• Copy-paste templates create generic, cookie-cutter content
• Templates can’t understand project context
• Maintaining templates is yet another task
• Templates don’t adapt to different project types

Manual Documentation Tools Are Too Slow

• Writing from scratch takes hours per project
• Context switching between building and documenting kills flow
• Inconsistency across different documentation types
• No integration with actual code/infrastructure

Existing AI Tools Aren’t Integrated

• ChatGPT requires manual copy-paste of context
• GitHub Copilot focuses on code, not documentation
• No tool understands the full project context across repos
• Switching between tools breaks the workflow

What I Needed:

• AI that understands my entire codebase context
• Automation that runs where I work (terminal, not browser)
• Documentation that matches my voice and technical depth
• Git workflows that enforce best practices automatically
• Content generation that produces portfolio-ready output

This project is about building that automation infrastructure from the ground up using Claude Code.

Solution Architecture

High-Level Design

The Claude Code Automation Infrastructure is a comprehensive system of specialized agents and slash commands that automate documentation, git workflows, and content generation directly in my development environment.

graph TB
    subgraph "Development Environment"
        A[Local Project] --> B[Claude Code CLI]
        B --> C[~/.claude/commands/]
        B --> D[~/.claude/docs/]
    end

    subgraph "Automation Agents"
        C --> E[Documentation Agent]
        C --> F[Git Workflow Agent]
        C --> G[Content Generation Agent]
    end

    subgraph "Documentation Agent"
        E --> H["generate-readme"]
        E --> I["generate-project"]
        E --> J["generate-blog"]
        E --> K["generate-wiki"]
    end

    subgraph "Git Workflow Agent"
        F --> L["git-commit"]
        F --> M["git-branch"]
        F --> N["github-create-repo"]
        F --> O["gitlab-create-repo"]
    end

    subgraph "Content Generation Agent"
        G --> P[Project Writeups]
        G --> Q[Blog Posts]
        G --> R[Wiki Documentation]
    end

    H --> S[README.md]
    I --> T[Portfolio Project]
    J --> U[Blog Post]
    K --> V[Wiki Page]

    L --> W[Conventional Commit]
    N --> X[GitHub Repo + Vercel]
    O --> Y[GitLab Repo + CI/CD]

    style B fill:#ff9900
    style E fill:#569a31
    style F fill:#527fff
    style G fill:#9b59b6

Key Components

1. Claude Code CLI Integration

Claude Code provides the foundation with:

• Full codebase context: Reads entire project structure
• File operations: Read, Write, Edit, Glob, Grep
• Git integration: Status, diff, commit, push
• Background execution: Long-running commands
• Stateful sessions: Maintains context across commands

2. Slash Command System (~/.claude/commands/)

Custom slash commands that trigger specialized workflows:

Documentation Commands:

/generate-readme    - Comprehensive README generation
/generate-project   - Portfolio project writeups
/generate-blog      - Technical blog posts (6 types)
/generate-wiki      - Wiki documentation (6 types)

Git Workflow Commands:

/git-commit         - Conventional commits with approval
/git-branch         - Feature branch creation
/github-create-repo - GitHub repo + Vercel deployment
/gitlab-create-repo - GitLab repo + CI/CD pipeline

3. Documentation Agent

The Documentation Agent analyzes projects and generates production-ready documentation:

Features:

• Context Analysis: Reads project structure, tech stack, dependencies
• Security Scanning: Detects and excludes sensitive files (.env, credentials)
• Intelligent Categorization: Classifies projects (AWS, homelab, AI tools, etc.)
• Template Selection: Chooses appropriate format based on project type
• Voice Consistency: Matches my writing style and technical depth

Output Types:

• README files with badges, installation steps, troubleshooting
• Portfolio project writeups with problem/solution/results
• Technical blog posts with code examples and explanations
• Wiki pages with categorization and tagging

4. Git Workflow Agent

Automates professional git practices:

Conventional Commits:

/git-commit
→ Analyzes: git status, git diff, git log
→ Determines: type (feat/fix/refactor), scope, subject
→ Generates: Detailed commit message with body and footer
→ Requests: Approval before committing
→ Executes: git add, git commit, git push
→ Includes: "🤖 Generated with Claude Code" attribution

Repository Creation:

/github-create-repo
→ Gathers: repo name, description, visibility
→ Creates: GitHub repository via gh CLI
→ Configures: Dual remotes (GitHub + GitLab)
→ Pushes: Initial commit
→ Sets up: Vercel auto-deployment

5. Content Generation Workflows

Blog Post Types:

1. Project Launch Announcements
2. How-To Guides & Tutorials
3. Lessons Learned & Post-Mortems
4. AWS Security Insights
5. Technical Deep Dives
6. Problem-Solution Narratives

Project Writeup Structure:

• Problem Statement (pain points, why it matters)
• Solution Architecture (diagrams, tech stack)
• Technical Implementation (code, configuration)
• Challenges & Solutions (what I learned)
• Results & Metrics (outcomes, performance)
• Future Enhancements (roadmap)

Wiki Documentation Types:

1. Process Documentation (workflows, procedures)
2. Technical Guides (setup, configuration)
3. Troubleshooting Guides (common issues, solutions)
4. Best Practices (patterns, anti-patterns)
5. Learning Notes (courses, certifications)
6. Tool Documentation (usage, tips)

Technical Implementation

Slash Command Architecture

Each slash command is a markdown file in ~/.claude/commands/ that provides instructions to Claude Code:

---
description: Generate comprehensive README for a project
---

You are helping Johnny generate professional README documentation.

## Your Task

1. **Analyze the project**:
   - Read project structure (find code files, configs, docs)
   - Identify tech stack from package.json, requirements.txt, etc.
   - Detect infrastructure patterns (Terraform, Docker, etc.)
   - Check for sensitive files to exclude

2. **Generate README sections**:
   - Project title and description
   - Tech stack with badges
   - Prerequisites and installation
   - Usage and configuration
   - Architecture (diagrams if complex)
   - Troubleshooting
   - Future enhancements

3. **Security considerations**:
   - Never include credentials, API keys, or secrets
   - Warn if sensitive files detected
   - Use placeholder values for configurations

4. **Output**:
   - Save to project root as README.md
   - Use proper markdown formatting
   - Include code blocks with syntax highlighting
   - Add mermaid diagrams for architecture

Context Management System

Internal Documentation (~/.claude/docs/):

~/.claude/docs/
├── automation-infra.md          # Project goals, environment, philosophy
├── workflow-design.md           # Git workflow, branching, approval process
└── documentation-agent-guide.md # Usage guide for documentation commands

This context is automatically included in Claude Code’s awareness, allowing it to:

• Remember my preferences and standards
• Understand project categorization
• Maintain consistent voice and formatting
• Follow my git workflow conventions

Dual Repository Strategy

GitHub (Public Portfolio):

• Username: hmbldv
• Purpose: Public portfolio, showcase projects
• Deployment: Vercel auto-deploy on push
• Audience: Recruiters, potential employers

GitLab (Private Development):

• Username: Private GitLab account
• Purpose: Private development, CI/CD experimentation
• Features: OIDC integration, automated testing
• Security: Private repos for work-in-progress

Workflow:

# Create on both platforms
/github-create-repo  → hmbldv/project (public)
/gitlab-create-repo  → <username>/project (private)

# Dual remote push
git push github main  → Public portfolio
git push gitlab main  → Private CI/CD

Portfolio Site Integration (Astro)

Content Collections:

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    tags: z.array(z.string()),
  }),
});

const projects = defineCollection({
  schema: z.object({
    title: z.string(),
    category: z.enum(['aws-security', 'aws-infra', 'homelab', 'ai-tools', 'local-dev', 'aws-ai']),
    status: z.enum(['in-development', 'launched', 'archived']),
    techStack: z.array(z.string()),
    repoUrl: z.string().url().optional(),
  }),
});

Generated Content Flow:

/generate-project (aws-sec)
→ Analyzes Terraform configs, GitLab CI/CD, AWS architecture
→ Generates src/content/projects/aws-security-infrastructure.md
→ Creates Mermaid diagrams for architecture
→ Includes problem statement, solution, results
→ Auto-deploys to Vercel on git push

Documentation Quality Standards

All generated content includes:

• Context-aware: Understands project type and target audience
• Technically accurate: Analyzes actual code, not assumptions
• Production-ready: No placeholders or TODOs
• Security-conscious: Never exposes credentials or sensitive data
• Consistent voice: Matches my technical writing style
• Properly formatted: Markdown, code blocks, diagrams
• SEO-friendly: Meta descriptions, tags, proper headings

Challenges & Solutions

Challenge 1: Claude Code Slash Command Loading

Problem: Newly created slash commands in ~/.claude/commands/ weren’t immediately available. Claude Code needed to be restarted to load them.

Impact: Broke the development flow during initial setup.

Solution:

• Documented the need to restart Claude Code after creating commands
• Worked around by manually executing command workflows during initial development
• Planned future: MCP server integration for dynamic command loading

Lesson Learned: Tool limitations should be documented early. Knowing you need to restart Claude Code prevents frustration.

Challenge 2: Context Size Management

Problem: Large codebases could exceed Claude’s context window, especially when analyzing multiple files for documentation.

Solution:

• Use targeted file reading instead of full codebase scans
• Leverage grep/glob for finding specific patterns
• Focus on key files (package.json, README, main code files)
• Exclude node_modules, build artifacts, .git directories

Result: Documentation generation works efficiently even on large projects like the portfolio site (100+ files).

Challenge 3: Git Workflow Consistency

Problem: Manual git operations resulted in inconsistent commit messages and missed steps (forgetting to push to both remotes, skipping conventional commit format).

Solution: Created /git-commit workflow that:

1. Analyzes changes with git status and git diff
2. Determines conventional commit type (feat/fix/refactor/etc.)
3. Generates detailed commit message following conventions
4. Shows preview and requests approval
5. Executes commit with proper format and attribution
6. Pushes to configured remotes

Lesson Learned: Automation should guide best practices, not just execute commands. The approval step ensures I review changes while the automation handles formatting.

Challenge 4: Dual Remote Management

Problem: Working with both GitHub (public) and GitLab (private) required remembering which remote to push to, leading to mistakes.

Solution: Created repository creation commands that:

• Configure both remotes with clear naming (github, gitlab, origin)
• Document which remote is for what purpose
• Provide commands for pushing to specific or both remotes
• Set up Vercel deployment on GitHub automatically

Current Setup:

git remote -v
github  git@github.com:hmbldv/portfolio.git
gitlab  git@gitlab.com:<username>/portfolio.git (if configured)
origin  git@github.com:hmbldv/portfolio.git

Challenge 5: Documentation Voice Consistency

Problem: AI-generated documentation often sounds generic or robotic, not matching my personal technical writing style.

Solution: Created internal documentation (~/.claude/docs/automation-infra.md) that captures:

• My learning philosophy (security-first, production-grade, cost-aware)
• Communication preferences (technical depth, no fluff)
• Project categorization system
• Target audience expectations

Result: Generated documentation now sounds like me writing it, with appropriate technical depth and personality.

Results & Metrics

Productivity Gains

Documentation Speed:

• Before: 2-4 hours to write a comprehensive README
• After: 5 minutes with /generate-readme
• Improvement: ~95% time reduction

Project Writeups:

• Before: Never completed (too time-consuming)
• After: 10 minutes with /generate-project, portfolio-ready
• Result: Can now document every project

Blog Posts:

• Before: 4-6 hours per technical blog post
• After: 15 minutes with /generate-blog, then quick review/edit
• Improvement: ~90% time reduction

Git Operations:

• Before: 2-3 minutes per commit (thinking, formatting, remembering conventions)
• After: 30 seconds with /git-commit (review and approve)
• Improvement: ~75% time reduction + 100% consistency

Quality Improvements

Documentation Quality:

• ✅ Comprehensive README files for all projects
• ✅ Consistent formatting and structure
• ✅ Security considerations (no exposed credentials)
• ✅ Proper code examples with syntax highlighting
• ✅ Architecture diagrams (Mermaid)

Git Commit Quality:

• ✅ 100% conventional commit format adherence
• ✅ Detailed commit bodies explaining changes
• ✅ Proper scoping (feat, fix, refactor, etc.)
• ✅ Consistent attribution (“Generated with Claude Code”)

Content Portfolio:

• ✅ AWS Security Infrastructure project documented
• ✅ Responsive design blog post completed
• ✅ Claude Code automation project writeup created
• ✅ Ready to scale to more projects

Infrastructure Metrics

Automation Coverage:

• ✅ Documentation generation: 4 commands
• ✅ Git workflows: 4 commands
• ✅ Repository management: 2 commands
• ✅ Portfolio integration: Fully automated

Portfolio Site Performance:

• ✅ Lighthouse scores: 100 across all metrics
• ✅ Build time: <1 minute (Astro optimization)
• ✅ Deployment: Automatic via Vercel
• ✅ Responsive design: Mobile-first, 320px-4K support

Key Takeaways

1. AI-Powered Automation Transforms Productivity

The 10x productivity gain isn’t hype—it’s real when you integrate AI into your actual workflow. Claude Code running in the terminal where I work is fundamentally different from ChatGPT in a browser tab.

Why it works:

• No context switching (stays in terminal/IDE)
• Full codebase awareness (reads files, understands structure)
• Persistent context (remembers project details)
• Action-oriented (writes files, runs git commands)

2. Documentation Automation Enables Consistency

When documentation is automated, it gets done. When it’s manual, it gets skipped. The automation doesn’t just save time—it enforces a standard of quality I wouldn’t maintain manually.

3. Slash Commands Are Better Than Prompts

Typing /generate-readme is faster and more consistent than explaining what I want each time. The slash command encodes best practices, security checks, and formatting preferences.

Comparison:

• Prompt: “Can you write a README for my project that includes installation, usage, and…”
• Slash Command: /generate-readme → Done

4. Approval Workflows Build Trust in Automation

The /git-commit command doesn’t automatically commit—it shows me what it will do and asks for approval. This builds trust in the automation while maintaining control.

Principle: Automate the tedious, not the critical decisions.

5. Internal Documentation Scales AI Context

The ~/.claude/docs/ directory acts as persistent memory for Claude Code. Instead of re-explaining my preferences each session, they’re documented once and referenced automatically.

Impact: New documentation commands inherit my writing style without additional prompting.

6. Multi-Modal Content Generation Reduces Bottlenecks

Having commands for READMEs, blog posts, project writeups, and wiki pages means I never have a “documentation backlog” anymore. Each project can be documented as it’s built.

7. Git Automation Enforces Best Practices

I’m still learning professional git workflows. The automation doesn’t just save time—it teaches me best practices through consistent examples.

Side Effect: I’m internalizing conventional commit formats by seeing them generated correctly every time.

v2.0 Update: Project Versioning Automation

The Problem

As the portfolio grew, I needed a way to manage project evolution. Some projects (like AWS Security Infrastructure) transformed from simple foundations into comprehensive platforms. But manually creating version archives, updating frontmatter, and maintaining consistency across files was tedious and error-prone.

The versioning system itself became a candidate for automation.

New Slash Command: /create-previous-version

Added a new slash command that automates the entire version archiving workflow:

/create-previous-version
→ Asks: Which project to archive?
→ Reads: Current project frontmatter (version, title, etc.)
→ Reviews: Git history for undocumented changes
→ Creates: v1-0.md snapshot with previous version metadata
→ Updates: index.md with majorVersions array reference
→ Commits: Both files with conventional commit message

The command performs:

1. Git History Review: Checks recent commits for undocumented changes before archiving
2. Content Validation: Ensures the archive is complete and accurate
3. Frontmatter Updates: Adds versionStatus: "previous", currentVersion, previousDate
4. Version Array Management: Adds entry to majorVersions in current version
5. Filename Convention: Uses dash format (v1-0.md) to avoid Astro’s dot-as-extension parsing

Content Strategy Automation

The versioning journey revealed a key insight: not everything should be versioned. This led to adding content strategy logic to the automation:

Versioning Decision Tree:

Is this a major project evolution?
├── Yes: New features, architecture changes, significant scope expansion
│   └── Create version archive
└── No: Documentation improvements, formatting, minor updates
    └── Use changelog entry only

Implemented in /create-previous-version:

• Reviews diff between v1-0.md and index.md
• Warns if content is identical (versioning not needed)
• Suggests changelog entry as alternative
• Prevents version bloat

Slash Command Inventory Update

Documentation Agent (4 commands):

• /generate-readme - Comprehensive README generation
• /generate-project - Portfolio project writeups
• /generate-blog - Technical blog posts (6 types)
• /generate-wiki - Wiki documentation (6 types)

Git Workflow Agent (4 commands):

• /git-commit - Conventional commits with approval
• /git-branch - Feature branch creation
• /github-create-repo - GitHub repo + Vercel deployment
• /gitlab-create-repo - GitLab repo + CI/CD pipeline

NEW: Content Management Agent (1 command):

• /create-previous-version - Archive current version before major updates

Technical Implementation

Command Structure (~/.claude/commands/create-previous-version.md):

---
description: Archive current project version before a major update
---

You are helping Johnny archive the current version of a project writeup
before making major changes.

## Step 1: Identify the Project
Ask which project to archive, read current frontmatter.

## Step 2: Perform Full Repo Context Review
Check git history, compare content with actual project state,
report discrepancies.

## Step 3: Create Previous Version File
Copy index.md to v[X-0].md, update frontmatter with:
- versionStatus: "previous"
- currentVersion: "[project-slug]"
- previousDate: [TODAY]

## Step 4: Update Current Version Reference
Add to majorVersions array, bump version, add changelog entry.

## Step 5: Verify and Commit
Check URLs work, commit with /git-commit workflow.

Lessons Learned

1. Automation Should Guide Content Strategy

The versioning command doesn’t just create files—it makes recommendations about whether versioning is appropriate. This prevents the common mistake of over-versioning (every minor change becomes a “major version”).

2. Git History is Valuable Context

By reviewing git history before archiving, the automation ensures version snapshots are accurate. This caught several instances where project writeups were outdated compared to actual code changes.

3. Filename Conventions Matter

Discovered that Astro treats dots in filenames as extensions (v1.0.md → slug v10). The automation now enforces dash format (v1-0.md) automatically.

4. Compound Automation Multiplies Value

The /create-previous-version command calls other commands (/git-commit), creating a pipeline. This compound automation handles the entire workflow without manual intervention between steps.

Future Enhancements

Phase 2: Advanced Documentation Features (Planned)

Screenshot and Diagram Automation:

• Automatic screenshot capture integration
• Architecture diagram generation from Terraform/CloudFormation
• Code flow diagrams from source analysis
• Integration with mermaid-cli for diagram rendering

Multi-Project Documentation:

• Cross-project linking in wiki
• Project series (Part 1, Part 2, etc.)
• Tag-based project grouping
• Timeline view of projects

Phase 3: Enhanced Git Workflows

Pull Request Automation:

• /create-pr command with auto-generated description
• PR templates based on change type
• Automatic reviewer suggestions
• Link to related issues/projects

Branch Management:

• Automatic branch cleanup (delete merged branches)
• Branch naming conventions enforcement
• Stale branch detection and notifications

Phase 4: CI/CD Integration

Pipeline Automation:

• Terraform plan/apply automation in GitLab CI
• Security scanning integration (tfsec, checkov)
• Cost estimation with Infracost
• Automated testing with Terratest

Deployment Automation:

• Preview deployments for branches
• Rollback commands
• Health check integration
• Slack/Discord notifications

Phase 5: Knowledge Management

Wiki Enhancement:

• Automatic wiki updates from code comments
• Learning progress tracking (certifications, courses)
• Resource library (bookmarks, articles, videos)
• Search across all documentation types

Content Intelligence:

• Suggest blog topics based on recent projects
• Detect duplicate content
• Auto-generate “related posts” links
• SEO optimization suggestions

Phase 6: MCP Server Integration

Model Context Protocol:

• Build custom MCP server for portfolio operations
• Dynamic slash command loading (no restart required)
• Real-time content preview
• Integration with external tools (Notion, Linear, etc.)

Resources

Project Links

• Portfolio Repository: github.com/hmbldv/portfolio
• Live Portfolio: Coming soon (Vercel deployment)
• Claude Code: claude.com/claude-code

Documentation

• Slash Commands: ~/.claude/commands/ in my development environment
• Internal Context: ~/.claude/docs/automation-infra.md
• Workflow Design: ~/.claude/docs/workflow-design.md

Related Blog Posts

• Modernizing My Portfolio: A Deep Dive into Responsive Design
• Coming Soon: “Building a Documentation Agent with Claude Code”
• Coming Soon: “From Zero to Portfolio: Automating Content Creation”

Tools & Technologies

• Claude Code: AI-powered development environment
• Astro: Modern static site generator
• Vercel: Deployment and hosting
• Git: Version control
• GitHub/GitLab: Repository hosting and CI/CD
• Markdown: Content format
• Mermaid: Diagram generation

---

This project demonstrates proficiency in: AI Integration • Automation Engineering • Developer Productivity • Documentation Systems • Git Workflows • Content Strategy • DevOps Practices

Built to solve my own documentation bottleneck while preparing for AWS Security Specialty certification