A public, evolving reference for how I usually structure, build, validate, and maintain software projects with AI agents.
Personal, not universal. Defaults, not mandates. Project-local context takes precedence.
I work on software projects with coding agents such as ChatGPT, Claude Code, Codex, and similar tools. Across projects, the same engineering questions recur: how much validation is enough, when CI is worth adding, when a dependency is justified, when a Release is meaningful, when an operation needs explicit approval, and how much context an agent should receive up front.
This repository reduces that repeated decision and communication cost. It records the defaults I tend to prefer so capable agents can reuse them as secondary context instead of reconstructing them from scratch in every conversation.
This repository contains:
- Preferences — relatively stable engineering tendencies;
- Decision Rules — how I usually handle recurring engineering choices;
- Project Conventions — how I usually structure and maintain projects once a choice has been made;
- Used in Practice — selected public examples showing where these preferences and decision rules are already adopted, without claiming that they caused better outcomes;
- AGENTS.md template — a lightweight starting point for project-local agent instructions.
The repository is intentionally opinionated because it documents my working preferences. It is not intended to establish industry consensus.
It is not an industry standard, universal software-engineering methodology, compliance framework, project scoring system, mandatory repository template, or substitute for understanding the target project's own goals and constraints.
When working on one of my projects:
- inspect the actual project state;
- read the target repository's own instructions first;
- understand the project's goals, constraints, users, and maturity;
- use this repository only as reusable secondary preference context;
- apply only the preferences that materially fit the project;
- prefer project-local evidence and instructions when they conflict with this repository;
- do not perform destructive or high-impact actions without explicit authorization.
The goal is to reduce repeated explanation, not to replace engineering judgment.
The current preferences emphasize:
- project outcomes over cross-project convention;
- verifiable results over plausible-looking output;
- reversible, reviewable changes over unnecessary blast radius;
- explicit project context over hidden local knowledge;
- dependencies that justify their maintenance cost;
- deliberate privacy, permission, and public/private boundaries;
- portability and local execution when they provide concrete value.
See Preferences for the current wording.
This repository is an evolving personal reference. Rules should be added only when they reduce recurring engineering decisions or recurring agent communication.
Before this positioning, the repository hosted Agentic Engineering Review, an evidence-first project-review system. That design remains preserved in the historical v0.4 release. The current repository no longer maintains the diagnostic scoring or review-protocol product as its primary direction.
Run:
python3 scripts/validate_repo.py
See CONTRIBUTING.md.
Licensed under the Apache License 2.0.