Team Guidelines and Shared Practices
💡 Practical note:
The dissemination of secure development practices depends not only on technical rules, but also on culture, practical examples and active sharing among team members.
Platforms such as Confluence, GitHub Wiki, Notion, Google Docs or even Markdown files versioned in the repository can be used to keep guidelines accessible and contextualised.
These guidelines must evolve over time and reflect both organisational policy and the real errors and improvements observed in projects.
📌 Objectives
- Consolidate and disseminate secure development practices among team members.
- Reduce reliance on repetitive manual validations.
- Make recurring security decisions and technical validation criteria explicit.
- Support the technical onboarding of new developers.
- Promote continuous improvement and living documentation.
👥 Who should apply it
- The whole development team: contributes to the improvement and adoption of the guidelines.
- Technical leads (tech leads, senior devs): curation, validation and regular updating.
- Security / AppSec: ensures alignment with organisational policies.
⏱️ When to apply it
- During the initial technical planning of a project or component.
- As part of the onboarding of new team members.
- After incidents, reviews or internal audits.
- Whenever recurring patterns of failures or exceptions emerge.
🧱 Recommended requirements
-
Document secure practices, examples and accepted patterns
- By technology stack or type of application (frontend, backend, API, etc.)
-
Keep the guidelines versioned and accessible
- Ideally alongside the code or in an integrated knowledge base.
-
Update the guidelines based on real errors
- Include real examples of findings and how to avoid or fix them.
-
Integrate the guidelines into team rituals
- E.g. weekly review, pull request clinic, tech talks or retros.
-
Promote sharing across teams
- Reuse patterns, secure snippets, avoidable anti-patterns.
✅ How to validate
- Explicit reference to the guidelines in PR templates.
- Inclusion of a link to the relevant guideline section in technical reviews.
- Records of periodic review and updating of the document.
- Visible adoption in code examples and in the most recent projects.
🧾 How to evidence it
guidelines/repository versioned per project or per stack.- Wiki or shared document with revision history.
- Mapping between recurring findings and guideline sections.
- Inclusion in the onboarding plan or in the new-member checklist.
🔄 Link to other practices
| Theme | Associated file |
|---|---|
| Secure coding good practices | addon/01-boas-praticas-codigo.md |
| Validation by linters and reviewers | addon/02-linters-validacoes.md, addon/08-validacoes-codigo.md |
| Justification of exceptions | addon/05-excecoes-e-justificacoes.md |
| Traceability of validations | addon/09-anotacoes-evidencia.md |
📌 Guidelines are the link between organisational policy and the team's concrete practice.
They must be useful, living and continuously improved based on the technical reality of projects.