playbook/README.md

tsl-playbook

TSL Playbook：Tinysoft Language（.tsl / .tsf）工程规范与代理规则合集。

目标

• 让代码易读、易维护、易演进。
• 风格保持一致，减少无意义的差异。
• 在不影响清晰度的前提下，尽量简洁。

原则

1. 可读性优先：读代码的时间远大于写代码。
2. 一致性优先：同一仓库内保持一致比追求“最优风格”更重要。
3. 遵从既有代码：修改/扩展现有代码时优先沿用其局部风格。

适用范围

• 本指南适用于所有 TSL 相关仓库与脚本。
• 当现有代码与本指南冲突时，以保持局部一致性为优先，逐步迁移。

docs/（开发规范）

docs/ 目录是给开发者阅读的工程规范，约束代码写法、命名与提交信息。

• docs/code_style.md：代码结构、格式、begin/end 代码块、注释与通用最佳实践。
• docs/naming.md：TSL 命名规范（顶层声明、文件同名规则、变量/成员/property、常量、集合命名等）。
• docs/commit_message.md：提交信息与版本号规范（type/scope/subject/body/footer、可选 Emoji 图例、SemVer）。

.agents/（代理规则）

.agents/ 目录是给自动化/AI 代理在本仓库内工作时遵守的规则，与 docs/ 并行。

• .agents/index.md：代理规则索引、适用范围与工作原则。
• .agents/auth.md：安全与鉴权边界、敏感信息处理要求。
• .agents/performance.md：性能优化原则、流程与验证要求。
• .agents/code_quality.md：代码质量底线与 review 清单。
• .agents/testing.md：测试策略与何时补测试。

版本与贡献

• 本项目会持续迭代；变更以 PR 形式提交。
• 新规则需包含动机、示例、迁移建议（如有）。