Personal field log / 2026
A working record of how I use agents to move from an open question to a tested, usable product.
Rather than setting an agent loose, we write the development document together: requirements analysis, module design, task breakdown, tool configuration, acceptance criteria, following a software-engineering process shaped for agents. What comes out is one document read two ways, structured enough for an agent to build from and complete enough for a person to audit.
Selected Works
Coding
How I Use Agents
Notes on how I use, configure, and understand agents in real workflows.
A continuing record of building a personal AI system, from setup to multi-agent workflows.
Codex Setup
The coding rules are based on Andrej Karpathy's summary of LLM coding pitfalls, addressing wrong assumptions, hidden confusion, missing trade-offs, and over-engineering.
When a request is ambiguous, confirm the goal, scope, and trade-offs before letting the Agent guess.
Turn changes into tests, type checks, builds, or observable results that prove the goal was met.
Respect existing code and user changes instead of turning one request into an unrelated refactor.
# AGENTS.md
_These are the user's non-negotiable rules. Follow and re-check them in context at all times._
## System Awareness
**System:** Windows 11 | **Shell:** Git Bash
- Run Windows-native commands through `cmd /c` or `powershell -Command`.
- Python 3.13 and Java 17 are installed.
- Git user: yking / 3202708371@qq.com
## Coding Rules That Reduce Common LLM (Your) Mistakes
**Trade-off:** These rules favor caution over speed. Use judgment for simple tasks.
### 1. Ask Questions and Clarify Requirements
**When the user gives a coding task, do not rush into implementation. Clarify the requirements until you are confident about the ideal outcome.**
Before you are at least 95% sure about the user's ideal implementation:
- Keep asking about implementation directions and possibilities related to the task.
- Ask which direction the user prefers when several are possible.
- Clarify how high-impact details should be handled.
- Do not change a single line without a clear direction.
### 2. Think Before Coding
**Do not jump to conclusions. Do not hide confusion. Weigh trade-offs honestly.**
Before implementation:
- State your assumptions explicitly. Ask when something is unclear.
- If there are multiple interpretations, present them. Do not choose silently.
- If there is a simpler approach, propose it. Stand your ground when necessary.
- If something is unclear, stop. Say what confuses you. Then ask.
### 3. Simplicity First
**Solve the problem with the least code. Do not write speculative code.**
- Do not add features beyond the requirement.
- Do not abstract one-off code.
- Do not add unrequested flexibility or configurability.
- Do not handle cases that cannot occur.
- If you wrote 200 lines for a 50-line problem, rewrite it.
- Prefer mature third-party libraries over building your own.
Ask yourself: "Would a senior engineer consider this too complex?" If so, simplify.
### 4. Precise Changes
**Touch only what must change. Clean up only the mess you made.**
When editing existing code:
- Do not improve adjacent code, comments, or formatting.
- Do not refactor parts that are not broken.
- Match the existing code style, even if you would write it differently.
- If you find unrelated dead code, point it out. Do not delete it.
When your change orphans code or files:
- Delete imports, variables, or functions that became useless because of your change.
- Do not delete existing invalid code unless asked.
Test: every line of the diff should trace directly to the user's requirement.
### 5. Goal-Driven Execution
**Define success criteria. Iterate until verification passes.**
Turn tasks into verifiable goals:
- "Add validation" becomes "write tests for invalid input and make them pass."
- "Fix a bug" becomes "write a test that reproduces the bug, then make it pass."
- "Refactor X" becomes "make sure tests pass before and after the refactor."
For multi-step tasks, briefly state the plan:
```
1. [Step] -> Verify: [Check]
2. [Step] -> Verify: [Check]
3. [Step] -> Verify: [Check]
```
Clear success criteria let you iterate independently. Vague criteria require constant clarification.
**Signs these rules work:** fewer unnecessary changes in the diff, fewer rewrites caused by over-complexity, and clarifying questions asked before implementation instead of after mistakes.
## Python Project Development
### Virtual Environments
Each Python project should use its own virtual environment (`venv`, `virtualenv`, or `conda`) instead of installing dependencies globally.
**Why:** Prevent dependency conflicts between projects, keep environments reproducible, and make dependency management and team collaboration easier.
**How to apply:** Identify all project dependencies, create the virtual environment, and install dependencies there. Manage versions through `requirements.txt` or `pyproject.toml`.
## Error Recovery
**Error recovery:** Every mistaken operation caused by a misunderstanding, whether in file content, file location, or the operation itself, must be immediately withdrawn, reverted, or corrected so it cannot affect later work.
## Clean Up Temporary Files
Temporary files created for tests or one-off checks must be cleaned up when the project is complete. Ask before cleaning them.
## Comments for Code Optimization and Bug Fixes
**Write comments for the new code, not the old code. Explain how the new code is meant to be used, not how it was changed. Before writing a comment, ask: "What does someone who has never seen this code need to know to understand it?"**
- Comments help understanding. They do not record modification history or the debugging process. Do not write comments such as "Deleted formulaToDb (it was unused, added the call after the bug fix)." That kind of statement belongs in the conversation's review summary.
## Emoji Usage
**Important: Misusing emoji can cause coding errors.**
When generating content:
- Emoji are allowed only in Markdown and plain-text files (`.md`, `.txt`, `.rst`).
- Emoji are forbidden in source files (`.py`, `.js`, `.ts`, `.json`, `.yaml`, `.xml`, and similar formats).
---
The agent may keep enriching this file through the conversation. Suggested additions must be reusable behavioral rules. If a suitable rule emerges, ask the user before adding it.
My Way of Using Agents
Confirm the goal, boundaries, and acceptance criteria before moving in the wrong direction.
Break requirements into tasks, dependencies, and expected outcomes with clear context for the agent.
Use the right models, tools, and sub-agents for each task while continuously realigning the direction.
Automated tests run alongside manual ones: check the code and the features, keep the evidence, and iterate from there.
Rather than setting an agent loose, we write the development document together: requirements analysis, module design, task breakdown, tool configuration, acceptance criteria, following a software-engineering process shaped for agents. What comes out is one document read two ways, structured enough for an agent to build from and complete enough for a person to audit.
Plugin Tools
GitNexus indexes a codebase into a knowledge graph, then exposes call relationships, dependencies, execution flows, and change impact through CLI and MCP.
It is not only for “write this snippet.” It answers “how is this code related to the rest of the project?” I use it to fill in context before exploring unfamiliar code, debugging, or editing.
Analyze, refresh, and inspect indexes from the CLI
Expose code relationships for Agent queries
Dependencies, call chains, and execution flows
Visual relationship map
I usually ask the Agent to place GitNexus between understanding and editing: build the index, query context, assess impact before changes, then inspect the changed scope afterwards.
Run analyze so project structure, symbol relationships, and execution flows become queryable.
Use exploring, query, and context to find relevant flows, callers, and callees.
Before changing a function or module, inspect upstream dependents and the likely risk boundary.
After editing, run detect_changes to confirm the affected scope matches the intention.
Superpowers is a complete software development methodology for coding agents, built from composable skills and initial instructions.
It does not jump from a request straight into code. It clarifies the goal, validates a design, creates an implementation plan, then works through each task with testing and review.
View Superpowers repositoryThe Agent selects relevant skills from the task itself without requiring a separate workflow switch.
Key workflows are treated as required stages rather than optional suggestions.
Complex plans can be assigned task by task, with each result checked before work continues.
Implementation, testing, and review alternate so issues are handled before the next stage.
The basic workflow
From shaping an idea to finishing a development branch, each stage produces something concrete and a checkpoint before the next stage.
Refine rough ideas through questions, explore alternatives, validate the design in sections, and save the design document.
After design approval, create an isolated branch and worktree, run setup, and verify a clean test baseline.
Break the work into bite-sized tasks with concrete file paths, code, and verification steps.
A fresh subagent can implement and review each task, or the current session can execute the plan inline.
Follow RED-GREEN-REFACTOR: watch a test fail, write the minimal implementation, then verify it passes.
Review each task against the plan, report issues by severity, and block progress on critical problems.
Verify tests, choose merge, PR, keep, or discard, and clean up the worktree.
A rough idea converges into a reviewed design ready for implementation.
The design becomes bite-sized tasks with files, code, and verification steps.
After testing and review, the branch can be merged, opened as a PR, or cleaned up.
Selected MCP tools
MCP is an interface for capabilities an Agent can call. This is a short record of tools I use or follow and the missing piece each one adds to development.
Playwright MCP gives an Agent browser automation capabilities: navigate pages, read accessibility structure, interact with UI, and inspect real results.
For web acceptance checks, mobile layout inspection, interaction regressions, and screenshots. It turns “the page should work” into an observable check.
GitNexus MCP exposes local knowledge-graph queries, context, impact analysis, and change detection to an Agent.
When I need project structure, call-chain tracing, change-impact reasoning, or diff-scope checks. It supplies context without replacing my final judgment.
Skill Directory
Repeated code understanding, debugging, and change-review work is organized into reusable skill files. Every skill keeps the full SKILL.md; this index shows only the summary.
Treat visual direction, typography, color, and interaction as one system so a page develops a clear point of view.
Set direction → define tokens → shape information → build interaction → inspect screenshots
Turn one-off prompts into reusable skills and improve them through test prompts and evaluation.
Define goal → draft → design tests → evaluate → iterate
Generate, edit, or compose bitmap assets when a task needs real visual material instead of a code-only approximation.
Clarify use → generate or edit → inspect asset → place in product context
For documents, PDFs, and spreadsheets, use the format-specific toolchain to generate, render, and verify deliverables.
Read request → choose format tool → generate → render-check → deliver
Scenarios at a Glance
12 min read
10 min read
11 min read
Let's collaborate on the next generation of agent-built applications.