AlexandreZanata/GoodPraticesForLLMSandAgents
GitHub: AlexandreZanata/GoodPraticesForLLMSandAgents
为 AI 编码 Agent 提供模块化的企业级工程规则库，涵盖架构约束、安全规范、测试标准与 token 高效加载机制。
Stars: 0 | Forks: 0
# LLM 和 Agent 的最佳实践
[](LICENSE)
[](https://github.com/AlexandreZanata/GoodPraticesForLLMSandAgents/actions/workflows/harness.yml)
开源 **Agent Harness** — 面向编码 Agent 和 LLM 辅助项目的企业级、技术栈无关规则。
**对于编码 Agent：** 从 **[AGENTS.md](AGENTS.md)** 开始 — 通用入口点（Cursor、Claude Code、Codex 等）。
**语言策略：** 100% 英语 — 代码、文档、注释、提交和 Agent 输出。
## 这是什么
一个模块化的规则库 + 工具，为 AI 编码 Agent 提供：
- 分层的领域驱动架构约束
- 契合 OWASP Top 10:2025 的安全规则（Web/API，有效期涵盖至 2026 年）
- 面向使用工具的 AI Agent 的 OWASP Agentic Top 10:2026 (ASI01–ASI10)
- TDD 金字塔和覆盖率门禁
- Token 高效的条件加载（加载 2–6 条规则，而不是 61 条）
- 受 **[Ponytail](https://github.com/DietrichGebert/ponytail)** 启发的 YAGNI 规则 — 静态，无需插件（MIT 归属说明）
可在任何项目中作为 **git submodule**、**副本** 或 **fork** 使用。针对 **Cursor** 和 `.cursor/rules/` 进行了优化 — 无需 API 代理或外部工具。
## 仓库布局
```
rules/ # Modular rule files + manifest (open source)
AGENTS.md # Universal entry point for all coding agents
├── manifest.yaml # Trigger index for conditional loading
├── AGENT-CORE-PRINCIPLES.md
└── 00-core/ … 11-documentation-and-glossary/
harness/ # Install + resolve tooling
├── requirements.txt # Python deps (PyYAML)
├── install.sh # Install into any project
├── resolve-rules.sh # Keywords → rule files
└── inject-frontmatter.py
.cursor/rules/ # Cursor alwaysApply entry points (incl. ponytail.mdc)
```
## 快速开始
```
# 用于 harness scripts 的 Python deps (resolve-rules, inject-frontmatter)
pip install -r harness/requirements.txt
# 为 API + auth task 解析 rules
./harness/resolve-rules.sh api endpoint auth
# YAGNI / 最小化实现 (受 Ponytail 启发)
./harness/resolve-rules.sh yagni minimal ponytail
# 安装到另一个项目
./harness/install.sh /path/to/your-project
```
在 **Cursor** 中打开 — `.cursor/rules/` 会自动应用（包括 `ponytail.mdc`）。
完整的 Harness 文档：[harness/README.md](harness/README.md)
## Token 经济（内置）
| 技术 | 原因 |
|-----------|-----|
| 模块化文件 + `triggers` frontmatter | 每个任务仅加载相关规则 |
| 纯技术英语 | 对 LLM 的 BPE 高效 |
| 简短祈使句 | `Never hardcode secrets` > 段落 |
| 列表/表格 | 信息密集，易于解析 |
| 引用，而非重复 | 词汇表仅定义一次术语 |
| Ponytail 阶梯（静态） | 编写最少的代码；Harness 的安全/TDD 规则依然适用 |
参见 `rules/09-ai-agent-specific/token-economy.md`。
## 核心原则（摘要）
- **分层：** Interfaces → Application → Domain ← Infrastructure
- **Domain：** 业务规则、状态机、不可变事件
- **安全：** 契合 OWASP Top 10:2025 的规则 + OWASP Agentic 2026 (ASI01–ASI10)
- **测试：** 75% 单元测试 / 20% 集成测试 / 5% E2E；Domain 覆盖率 ≥ 90%
- **AI Agent：** 仅限 Application Layer；只读；由人类确认后方可持久化
完整契约：[rules/AGENT-CORE-PRINCIPLES.md](rules/AGENT-CORE-PRINCIPLES.md)
## 在你的项目中安装
```
# 新的 AI 辅助项目 (docs templates + harness)
./harness/bootstrap-project.sh /path/to/new-project
# 现有项目 (仅 harness)
git submodule add https://github.com/AlexandreZanata/GoodPraticesForLLMSandAgents.git .agent-harness
./.agent-harness/harness/install.sh . --symlink
```
当现有代码与这些规则之间存在疑问时，**以规则为准** — 除非针对某个任务被明确覆盖。
## 可选的本地覆盖
在 `.local/`（已 gitignore）中添加项目特定的规则 — 无需 fork 即可在此基础上叠加。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
第三方归属说明：[Ponytail](https://github.com/DietrichGebert/ponytail) (MIT) — 参见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
标签：AI代理, Cursor, Cutter, DLL 劫持, 大语言模型, 开发规范, 逆向工具