AI Workflows

Public AI-assisted work patterns and operating guides from Vivian Li.

Workflows

• Code Change Workflow — a safe, test-first process for AI-assisted software changes: define behavior, verify, review, then ship.

Use with coding agents

This repo is designed so you can copy a workflow into the instruction system for the coding agent you use most. The workflow file itself, code-change-workflow.md, is kept clean so users can download it and use it directly as a skill/instruction file.

Raw workflow URL:

https://raw.githubusercontent.com/viviannnl/ai-workflows/main/code-change-workflow.md

Claude Code: install as a skill

Claude Code skills are project-local folders inside .claude/skills/. Each skill folder has a SKILL.md file at the top, with optional supporting files underneath it.

From the root of the project where Claude Code will edit files:

mkdir -p .claude/skills/code-change-workflow
curl -L https://raw.githubusercontent.com/viviannnl/ai-workflows/main/code-change-workflow.md \
  -o .claude/skills/code-change-workflow/SKILL.md

Then add a short project instruction so Claude knows when to use it. If CLAUDE.md already has a “Code changes” section, edit that section instead of appending a duplicate.

cat >> CLAUDE.md <<'EOF'

## Code changes

For any code change, use the code-change workflow skill. Define behavior and success criteria before editing, use TDD where practical, verify with tests/build/lint/manual checks, review the diff, then commit/push only after validation.
EOF

How to use it in Claude Code:

Use the code-change workflow skill to fix this bug: 

Beginner note: .claude/skills/ is just a folder inside your project. A “skill” is a reusable Markdown instruction package Claude can load when the task matches. CLAUDE.md is the project note Claude reads for that repo.

Codex: use AGENTS.md as the equivalent

Codex does not need a Claude-style skill file. The closest equivalent is persistent project instructions, usually AGENTS.md, plus a local copy of this workflow.

From the root of the project where Codex will edit files:

mkdir -p docs/ai-workflows
curl -L https://raw.githubusercontent.com/viviannnl/ai-workflows/main/code-change-workflow.md \
  -o docs/ai-workflows/code-change-workflow.md

Then add a pointer in AGENTS.md. If AGENTS.md already has a “Code changes” section, edit that section instead of appending a duplicate.

cat >> AGENTS.md <<'EOF'

## Code changes

For any code change, first read and follow `docs/ai-workflows/code-change-workflow.md`.

Required behavior:
- Define the intended behavior and success criteria before editing.
- Use TDD where practical: write or update a failing test first, then implement the smallest fix.
- Verify with targeted tests, full relevant tests, lint/typecheck/build, and manual checks when the UI or app flow changes.
- Review `git diff` for scope, secrets, and unrelated files before committing.
- Commit and push only after validation, then monitor CI/deployment when applicable.
EOF

How to use it in Codex:

Follow AGENTS.md and the code-change workflow to implement: 

Beginner note: AGENTS.md is the common project instruction file many coding agents read before working. It is the Codex equivalent of “make this a reusable workflow,” even if Codex does not call it a skill.

Keep the workflow up to date

To refresh an existing copy later, rerun the same curl -L ... -o ... command in your project. Review the diff before committing the refreshed workflow:

git diff -- .claude/skills/code-change-workflow/SKILL.md docs/ai-workflows/code-change-workflow.md AGENTS.md CLAUDE.md