Operational Design Guide for Safer AI-Assisted Development

1. Why This Operating Method Is Needed

AI works very quickly when producing initial code from a short description, classifying logs, or drafting documentation. But when an existing repository, an active server, multiple configuration files, past decisions, and published documentation are involved, simply asking it to “fix things appropriately” is risky.

The problem is not that AI always makes mistakes. The problem is that, when the work remains broadly scoped, it becomes unclear which information is authoritative, which files may be changed, and what has actually been verified. The longer a conversation continues under those conditions, the more explanation accumulates while the deliverable itself stops moving forward.

1. Limit the task to one goal
2. Define the change boundary
3. Confirm the source of truth
4. Verify
5. Record and close out

2. Intended Readers and What This Guide Does Not Cover

What follows is one example of methods I have tried for using AI in real work. Use only the parts that fit your own environment.

3. Six Principles for AI-Assisted Development

In my environment, keeping the following six ideas in view made it easier to turn AI output into actual deliverables. They do not need to be adopted in exactly the same form, but it was useful to connect approval, change boundaries, the source of truth, verification, and records.

4. Small Approval Units

When a broad objective is handed to AI as-is, investigation, implementation, verification, documentation updates, and publication work become mixed in one conversation. Mixed work is harder to review and harder to roll back when something fails.

For that reason, I divide approvals into units that make both “what we will do this time” and “what we will not do this time” explicit. For example, read-only investigation, docs-only updates, implementation, runtime changes, and publication work are approved separately.

Poor example

Do everything required to publish this feature.

Better example

This time, update only docs/NOW.md and docs/CHANGELOG.md. The goal is to record the previous verification results and make the next SINGLE_ACTION clear. Do not touch server, Nginx, DNS, mail, or deploy settings.

5. Explicit Write Set

The write set is the list of files AI may edit for the current task. Without it, a request such as “fix whatever is necessary” may lead AI to modify surrounding files with good intentions.

The write set is not merely a task instruction; it is a safety boundary. Deciding which files should change makes Git diff review shorter and helps reveal unexpected side effects.

Approved write set:
- docs/NOW.md
- docs/CHANGELOG.md

Do not edit:
- public/**
- AGENTS.md
- README.md
- server/runtime/DNS/mail/deploy settings

Read set / write set / areas not to touch

For publication or server-related work, separate not only the files that may be edited but also what may be read and what must not be touched.

6. Git as the Source of Truth

Conversations with AI are convenient, but they are not suitable as the source of truth. They contain interim hypotheses, outdated assumptions, failed ideas, and unverified recollections.

In my environment, I determine the current state from GitHub remote main and the corresponding local worktree. Before and after work, I check HEAD, origin/main, remote refs/heads/main, and the worktree state. When using GitLab, Bitbucket, self-hosted Git, or feature branches, replace these with the remote repository and baseline branch agreed for the project.

git fetch origin main
git status --branch --short
git rev-parse HEAD
git rev-parse origin/main
git ls-remote origin refs/heads/main

7. Update Documentation Together with Implementation

If code is changed while documentation is postponed, the next AI or person may read outdated instructions and begin the wrong work. In my environment, gaps between implementation and documentation directly became incorrect assumptions in the next session.

More documentation is not automatically better. I assign distinct roles to documents and avoid repeating the same information.

The important point is not to add more explanation, but to leave enough information that the next task can begin without confusion.

8. Verification Logs

A statement such as “verified” does not show what was actually checked. A verification log should record the commands run, the targets checked, the results obtained, and the areas not verified.

Checks run:
- git fetch origin main
- git status --branch --short
- git diff --check
- Markdown fence / HTML comment / Jinja scan
- git rev-parse HEAD
- git rev-parse origin/main

Result:
- PASS
- HEAD == origin/main
- worktree clean

The purpose of a verification log is not to make AI’s explanation trustworthy, but to leave a state that a person can inspect later.

9. Close Out Implementation and Documentation Together

Closeout is the process of finalizing the state at the end of a task. When implementation, verification, documentation, commits, and the next action are left at different points in time, it becomes unclear what is complete and what remains unfinished.

A synchronized closeout records the changes, changed files, verification results, unverified items, commit, and next action as one unit.

Closeout:
- Result: PASS
- Changed files:
  - app/example.py
  - docs/NOW.md
  - docs/CHANGELOG.md
- Checks run:
  - pytest
  - git diff --check
  - parser-safety scan
- Commit: abc1234
- Final state:
  - HEAD == origin/main
  - worktree clean
- Next single action:
  - R4_PUBLICATION_READONLY_VERIFY

10. Separate Work Types and Risk Levels

Using the same process for a minor documentation update and an operation that affects production can either create excessive review or leave important approvals missing. I therefore use R0–R5 (the author’s example classification) to make work types and risk levels easier to distinguish.

This classification is not a general standard; it is an example from my own workflow. The important point is not the names R0–R5, but clearly distinguishing work with different characteristics, such as read-only work, documentation-only work, implementation, and production operations.

How This Classification Helped

• It avoids excessive preliminary work for simple tasks.
• It prevents high-risk work from proceeding under a lightweight approval.
• It reduces the chance that AI expands the scope during the task.
• It communicates the weight of a task quickly during handoff.

11. Create an Approval Template and Reuse the Same Format

When every request is written freely from scratch, the goal, change boundary, prohibited scope, or verification method may be omitted. I therefore created an approval template containing the necessary fields and reuse the same format.

The following is one example used in my environment. You do not need to adopt the same field names or structure. What matters is deciding which fields your environment needs—for example the goal, change boundary, areas not to touch, verification method, and stop conditions—and then using them consistently.

WORK_ID:
WORK_RANK:
GOAL:
SOURCE_OF_TRUTH:
REQUIRED_READS:
APPROVED_WRITE_SET:
FORBIDDEN_SET:
RESTRICTED_SECRET_MATERIAL:
ALLOWED_COMMANDS:
REQUIRED_CHECKS:
STOP_CONDITION:
DOCS_TO_UPDATE:
COMPLETION_CRITERIA:
OUTPUT_FORMAT:
NEXT_SINGLE_ACTION:

Template Example from My Environment

WORK_ID: R1_DOCS_ONLY_CLOSEOUT_SYNC_YYYYMMDD_01
WORK_RANK: R1_DOCS_ONLY
GOAL: Record the latest verification results in docs/NOW.md and docs/CHANGELOG.md.
SOURCE_OF_TRUTH: GitHub remote main and matching local worktree.
REQUIRED_READS:
- docs/NOW.md
- docs/CHANGELOG.md
APPROVED_WRITE_SET:
- docs/NOW.md
- docs/CHANGELOG.md
FORBIDDEN_SET:
- public/**
- server/runtime/DNS/mail/deploy settings
- unrelated files
RESTRICTED_SECRET_MATERIAL:
- .env
- SSH private keys
- API keys and access tokens
- files containing passwords, customer data, or personal data
ALLOWED_COMMANDS:
- git status / git diff / git diff --check / git rev-parse
REQUIRED_CHECKS:
- changed files exactly match approved write set
- Markdown parser-safety scan
- final HEAD == origin/main if commit/push is in scope
DOCS_TO_UPDATE:
- docs/NOW.md
- docs/CHANGELOG.md
COMPLETION_CRITERIA:
- verified facts and unverified items are recorded
- NEXT_SINGLE_ACTION is one item only
OUTPUT_FORMAT: closeout summary only
NEXT_SINGLE_ACTION: R2_DIFF_PLAN_FOR_NEXT_CHANGE

Benefits

• AI is less likely to expand the goal on its own.
• The review target becomes clear.
• History can be recorded in a consistent format.
• The template is easy to reuse as a prompt for Codex.
• Missing approvals or verification conditions are easier to identify before work begins.

12. Record Verified / Unverified / Next Separately

A major risk in AI-assisted development is that an unverified assumption gradually becomes treated as a verified fact. To prevent this, separate Verified, Unverified, and Next at the end of every work report.

Verified:
- docs/NOW.md and docs/CHANGELOG.md were updated.
- Changed files match the approved write set.
- Markdown parser-safety scan passed.
- HEAD == origin/main after push.

Unverified:
- Runtime state was not checked.
- Nginx reload/restart was not performed.
- DNS/mail/server settings were not changed.

Next:
- R2_DIFF_PLAN_FOR_PUBLICATION_ROUTE

Why Separate Them

Separating these three items distinguishes observed facts, unverified scope, and the next action. This makes it easier for the next worker to judge what can be trusted and what must not yet be treated as fact.

13. Stopping and Rollback When Work Fails

AI-assisted development should not assume that failures will never happen. It should assume that work can be stopped safely when failure occurs. Because problems can appear even after an item has been marked Verified, define the stopping procedure in advance.

Failure protocol:
1. Stop additional implementation
2. git status and git diff --stat to inspect the change scope
3. Save the diff if necessary
4. Record Verified / Unverified / Risks
5. A person decides whether to discard, revert, or redesign
6. Restart using HANDOFF_PROMPT.md or the closeout format

14. Session and Context Management

As a conversation becomes longer, old instructions, failed fixes, and interim hypotheses become mixed together, making it easier for AI to lose track of the current approval boundary. After one approval unit is complete, switch to a new session when appropriate.

Minimum information for restarting a session:
- Source of truth: GitHub remote main + local worktree
- Current HEAD / origin/main
- Approved WORK_RANK and write set
- Verified facts only
- Unverified items
- Next single action
- Forbidden set

15. Automating Secret-Leak Prevention

A reminder not to write secret information is not sufficient. Assuming that both people and AI make mistakes, I use mechanisms that detect accidental commits or secret material before publication.

16. JSON / YAML Approval Templates

If you want to reuse the template in tools or scripts, as I do, you can provide JSON or YAML in addition to Markdown. This is an optional example for readers who need it; Markdown or plain text is sufficient for ordinary chat use.

YAML version

work_id: R3_IMPLEMENTATION_EXAMPLE_YYYYMMDD_01
work_rank: R3_IMPLEMENTATION
goal: Implement the approved small change only.
source_of_truth:
  - GitHub remote main
  - Corresponding local worktree
approved_write_set:
  - app/example.py
  - tests/test_example.py
forbidden_set:
  - server/runtime/DNS/mail/deploy settings
  - unrelated files
restricted_secret_material:
  - .env
  - SSH private keys
  - API keys and access tokens
  - files containing passwords, customer data, or personal data
required_checks:
  - pytest
  - git diff --check
  - changed files match approved write set

JSON version

{
  "work_id": "R3_IMPLEMENTATION_EXAMPLE_YYYYMMDD_01",
  "work_rank": "R3_IMPLEMENTATION",
  "goal": "Implement the approved small change only.",
  "source_of_truth": ["GitHub remote main", "Corresponding local worktree"],
  "approved_write_set": ["app/example.py", "tests/test_example.py"],
  "forbidden_set": ["server/runtime/DNS/mail/deploy settings", "unrelated files"],
  "restricted_secret_material": [".env", "SSH private keys", "API keys and access tokens", "files containing passwords, customer data, or personal data"],
  "required_checks": ["pytest", "git diff --check", "write set verification"],
  "closeout_format": ["Result", "Changed files", "Verified", "Unverified", "Risks", "Next"]
}

17. Review Scope and Anti-Patterns

Small approval units are useful, but if they become too small, waiting for human review becomes a bottleneck. Choose a practical scope that balances safety and progress. The following 15–30 minute range is simply a guideline that I find manageable, not a general standard.

18. Minimal Prompt for Codex

A prompt for Codex or another AI development tool is not better merely because it is long. What matters is the source of truth, approved scope, prohibited scope, verification, stop conditions, and output format.

Use the local worktree as the source of truth.
Do not infer current state from chat history.

WORK_RANK: R3_IMPLEMENTATION
GOAL: Implement the approved small change only.
APPROVED_WRITE_SET:
- app/example.py
- tests/test_example.py
- docs/NOW.md
- docs/CHANGELOG.md
FORBIDDEN_SET:
- server/runtime/DNS/mail/deploy settings
- unrelated refactors
RESTRICTED_SECRET_MATERIAL:
- .env
- SSH private keys
- API keys / access tokens
- files containing passwords or personal data
REQUIRED_CHECKS:
- tests for changed behavior
- git diff --check
- changed files exactly match approved write set
- parser-safety scan for edited Markdown
STOP_CONDITION:
- stop if write set must expand
- stop if runtime/deploy operation becomes necessary
- stop if restricted secret material must be read or displayed
CLOSEOUT_FORMAT:
- Result
- Changed files
- Verified
- Unverified
- Risks
- Next

19. Usage Notes and License

This public guide organizes practical ideas for carrying out AI-assisted development more safely. It reflects observations from the author’s experience and does not guarantee compliance with any particular product, law, or security standard.

20. Summary

The important question in AI-assisted development is not whether AI is used. It is how much is delegated to AI and where people draw the boundary.

In my environment, small approval units, an explicit write set, Git as the source of truth, documentation sync, verification logs, and synchronized closeout made it easier to turn AI’s speed into actual deliverables.

Adding stopping procedures, session management, secret detection, JSON/YAML templates, and review-scope guidance also makes it easier to address problems that emerge after the workflow is in use.