DOCSEARCHbyAlgolia
Submit Docs

ckaserer.dev Blog

website·Indexed 31 days ago

https://ckaserer.dev/

Technical blog by an engineering leader and Azure architect focusing on AI-first delivery, cloud architecture, and DevOps practices. Topics include Git worktrees for coding agents, squash-merging in trunk-based development, and Copilot enablement workshops.

Tokens
1.8K
Snippets
4
Records
14
Agent score
57%

What's inside ckaserer.dev

  1. Validate workshop materials for the 'curse of knowledge'

    When creating Copilot training materials, experts often overlook basic steps or terms (the 'curse of knowledge'). To fix this, use 'singing-and-clapping validation': run the material by someone with zero prior exposure to the topic. If the core idea cannot be conveyed without relying on unstated terms or prior steps, the material requires further simplification.

  2. Best practices for facilitating GitHub Copilot enablement workshops

    To ensure a successful hands-on GitHub Copilot workshop, focus on pre-session validation of technical prerequisites and audience segmentation. Many critical failures (network blocks, missing licenses, or skill gaps) do not manifest as 'raised hands' during the session, meaning they must be addressed before the workshop begins.

  3. Prevent agent race conditions using Git worktrees

    When running multiple coding agents (e.g., background subagents, interactive sessions, or automation) against a single repository, using a shared checkout creates a race condition on the .git index. Because a checkout has only one index and one HEAD, one agent's uncommitted edits or checkouts can silently overwrite another's without warnings or merge conflicts.

    To ensure isolation, every task should be assigned its own git worktree. Git enforces this isolation by refusing to check out a branch that is already checked out in another worktree.

  4. Implement Any Decision Records (ADR) to prevent AI agent regressions

    Any Decision Records (ADRs) are used to document non-trivial, hard-to-reverse decisions (e.g., deployment mechanisms, framework choices, storage layouts, or versioning policies). By storing these in a dedicated directory (typically docs/adr/), developers provide a guardrail for AI coding agents. Without this rationale, agents may perceive intentional trade-offs as 'bugs' or 'messy code' and attempt to 'fix' or 'simplify' them away. A structured ADR ensures the agent understands why a specific path was chosen and why alternatives were rejected.

  5. Determine when to create a Decision Record

    Not every choice requires a record. Use the following criteria to decide if a decision earns an ADR file:

    • Create a record if: The decision is non-trivial, hard to reverse, or if the question 'why not the obvious alternative?' is likely to be asked again.
    • Skip the record if: The choice is a reversible, low-stakes preference (these belong in a style guide or rule file).
    • The Litmus Test: If this record were deleted, would a future human or AI agent plausibly make a different, worse choice? If yes, write the record.

  6. Prepare GitHub Copilot workshop logistics and prerequisites

    Avoid common failure points by implementing the following checks before the workshop starts:

    • License Verification: Do not assume participants have licenses based on the invite. Send a confirmation email a few days prior to verify provisioning.
    • Network Validation: Test the actual network path. Corporate proxies may block Copilot traffic even if general Wi-Fi is available.
    • Facilitator Ratio: For hands-on sessions, maintain a ratio of approximately 4–5 participants per facilitator to ensure individuals don't get stuck.
    • Audience Segmentation: Use a one-line self-assessed skill question during sign-up. If the skill range is wide, split the group into different tracks to prevent beginners from disengaging while advanced users dominate the conversation.

  7. Implement squash-merge enforcement for trunk-based development

    When using trunk-based development (single main branch, short-lived PR branches), enforce a 'squash-merge only' policy in repository settings. This ensures that messy iterations, failed attempts, and AI-generated noise within a branch are collapsed into a single coherent commit on main. This is critical for maintaining a linear history, which is required for reliable git bisect operations and prevents delivery instability caused by large, fragmented AI-authored diffs.
    # Check if your main branch has non-linear history (commits with more than one parent)
git log --pretty="%P"
# Every line should have exactly one parent hash for a perfectly linear history

  8. Configure Claude Code worktree paths

    For Claude Code, worktrees should be located at .claude/worktrees/<branch-slug> and added to .gitignore. This specific path aligns with Claude Code's native EnterWorktree and ExitWorktree tooling, allowing the agent to create and remove worktrees without requiring extra confirmation prompts.
    # Example path for a task-specific worktree
.claude/worktrees/feature-branch-name

  9. Prevent OneDrive and SharePoint from syncing .git folders

    Git repositories generate high file churn within the .git folder, which can overwhelm the OneDrive sync engine and cause instability or sync conflicts. To resolve this, you can implement a machine-level OneDrive policy that instructs the sync engine to ignore folders named .git. This allows the working files to be synced to SharePoint/OneDrive while ensuring the Git remote remains the sole authoritative source of history.
    # Requires an elevated (Administrator) PowerShell session
New-Item -Path 'HKLM:\SOFTWARE\Policies\Microsoft\OneDrive\EnableODIgnoreFolderListFromGPO' -Force
New-ItemProperty -Path 'HKLM:\SOFTWARE\Policies\Microsoft\OneDrive\EnableODIgnoreFolderListFromGPO' `
  -Name '1' -PropertyType String -Value '.git' -Force

  10. Caveats for OneDrive .git exclusion policy

    When using the EnableODIgnoreFolderListFromGPO registry key to ignore .git folders, keep the following constraints in mind:

    • Scope: The policy is machine-local. On centrally managed workstations, this may need to be deployed via Group Policy or Intune.
    • Existing Data: This policy will not remove .git metadata that has already been uploaded to the cloud.
    • Backup: This does not make SharePoint a Git remote. Unpushed branches are not backed up; only a pushed remote ensures history is safe.

  11. Trade-offs of using one worktree per agent task

    While providing necessary isolation, the one-worktree-per-task approach has the following costs:

    • Dependency Overhead: Dependencies are not shared between worktrees; each requires its own installation.
    • Disk Usage: Disk space increases as each worktree duplicates the working tree.
    • Visibility: Reading an in-progress branch from another agent requires creating a separate worktree for that branch.

  12. Trade-offs of using squash-merge for PRs

    Using squash-merge as the exclusive merge strategy involves specific trade-offs:

    1. Loss of Granularity: Individual commits within a PR are not available for git blame on the main branch; only the final squashed diff and the PR description remain.
    2. PR Atomicity: If a PR contains several independent changes that might need to be reverted separately, they must be split into separate PRs rather than relying on individual commits within a single PR.
    3. Restriction: Disabling merge-commits and rebase-merges in repository settings removes those options for all contributors.